/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 0e2603c23f0747c5660669f946e231730af000c76d1653b153dcf2c26fce0a6b:


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 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
64c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
64d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
64e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
64f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6580: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6590: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
65a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
65b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
65c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
65d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
65e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
65f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6600: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6610: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6620: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6630: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6640: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6650: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6660: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6670: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6690: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
66a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
66b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
66c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
66d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
66e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
66f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6700: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6710: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6720: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6730: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6740: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6750: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6760: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6770: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6780: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6790: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
67a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
67b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
67c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
67d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
67e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
67f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6800: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6810: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6820: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6830: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6840: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6850: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6860: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6870: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6880: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6890: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
68a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
68b0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
68c0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
68d0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
68e0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
68f0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6900: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6910: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6920: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6930: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6940: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6950: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6960: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6970: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6990: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
69a0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
69b0: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
69c0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69d0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69e0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69f0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a00: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a10: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a20: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a30: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a40: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a50: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a60: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a70: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a90: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ab0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6ad0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6ae0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6bf0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6cc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6cd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6cf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d40: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d60: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6d70: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6d80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6d90: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6da0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6db0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6dc0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6dd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6de0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6df0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6e00: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6e10: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6e20: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e40: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e60: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e80: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6e90: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6ea0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6eb0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ed0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6ee0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6ef0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6f00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6f10: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6f20: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f30: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f40: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f50: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6f70: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6f80: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6f90: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6fa0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6fb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6fc0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6fd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6fe0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6ff0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
7000: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7010: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7020: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7030: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7040: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7050: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7060: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7070: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7080: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7090: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
70a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
70b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
70c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
70d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
70e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7100: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7110: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7120: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7130: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7140: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7150: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7160: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7170: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7180: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7190: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
71a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
71b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
71c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
71d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
71e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
71f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7200: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7210: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7220: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7230: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7240: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7250: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7260: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7280: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7290: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
72a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
72b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
72c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
72d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
72e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
72f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7300: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7310: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7320: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7330: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7340: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7350: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7360: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7370: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7380: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7390: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
73a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
73b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
73c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
73d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
73e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
73f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7400: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7410: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7420: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7430: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7450: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7460: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7470: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7480: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7490: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
74a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
74b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
74c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
74d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
74f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7500: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7510: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7520: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7530: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7540: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7550: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7560: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7570: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7580: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7590: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
75a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
75b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
75c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
75d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
75e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
75f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7600: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7610: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7620: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7630: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7640: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7650: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7660: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7670: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7680: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7690: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
76a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
76b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
76c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
76d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
76e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
76f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7700: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7710: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7720: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7730: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7740: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7750: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7760: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7770: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7780: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7790: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77a0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
77b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
77c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
77d0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
77e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
77f0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7800: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7810: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7820: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7830: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7840: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7850: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7860: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7870: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7880: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7890: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
78a0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
78b0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
78c0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
78e0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
78f0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7900: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7910: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7920: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7930: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7940: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7950: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7960: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7970: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7980: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7990: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
79a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79b0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
79c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
79d0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
79e0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
79f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7a00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7a10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7a20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7a70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7a80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7a90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7aa0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7ab0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7ac0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7ad0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7ae0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7af0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7b00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7b10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7b20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7b70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7b80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7b90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ba0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bc0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7bd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7bf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7c10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7c20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7c70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7c80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7c90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7ca0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7cb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7cc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7cd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ce0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7cf0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7d00: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7d10: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7d20: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d30: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d40: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d50: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7d70: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7d80: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7d90: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7da0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7db0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7dc0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7dd0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7de0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7df0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7e00: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7e10: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7e20: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e30: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e40: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e50: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e60: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7e70: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7e80: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7e90: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7ea0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7eb0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7ec0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7ed0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7ee0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7ef0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7f00: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7f10: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7f20: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f30: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f40: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f50: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f60: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7f70: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7f80: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7f90: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7fa0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7fb0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7fc0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7fd0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7fe0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7ff0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
8000: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8010: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8020: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8030: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8040: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8060: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8070: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8080: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8090: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
80a0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
80b0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
80c0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
80d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
80e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
80f0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8100: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8110: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8120: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8140: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8150: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8160: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8170: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8180: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8190: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
81a0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
81b0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
81c0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
81d0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
81e0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
81f0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8200: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8210: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8220: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8230: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8240: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8250: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8260: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8270: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8280: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8290: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
82a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
82b0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
82c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82d0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
82e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82f0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8330: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8350: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8370: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8380: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8390: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
83a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
83c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
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 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
8400: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a  LE_WHEN_OPEN].**
8410: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8420: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
8430: 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ERWRITE].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
8450: 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75  MMUTABLE].** </u
8460: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8470: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8480: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8490: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
84a0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
84b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
84d0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
84e0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
84f0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8500: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8510: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8520: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8530: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8540: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8550: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8560: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8580: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8590: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
85a0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
85b0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
85c0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
85d0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
85e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
85f0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8600: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8610: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8620: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8630: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8640: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8650: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8660: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8670: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8680: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8690: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
86a0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
86b0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
86c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
86d0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
86e0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
86f0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8700: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8710: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8720: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8730: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8740: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8750: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8760: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8770: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8780: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8790: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
87a0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
87b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
87c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
87d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
87e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
87f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8800: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8810: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8820: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8830: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8840: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8850: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8860: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8870: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8880: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8890: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
88b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88d0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8900: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8910: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8920: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8930: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8940: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8950: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8960: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8970: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8980: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8990: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
89a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
89c0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
89d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
89f0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8a00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a10: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8a20: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8a30: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8a40: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8a50: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8a60: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8a70: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8a80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8aa0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8ab0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8ac0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8ad0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8ae0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8af0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8b00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8b10: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8b20: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8b40: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8b50: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8b60: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8b80: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8b90: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8ba0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8bb0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8bc0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8bd0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8be0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8bf0: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8c00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8c10: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c20: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c30: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8c40: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c50: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8c70: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8c80: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8c90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8ca0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8cb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8cc0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8cd0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8ce0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8cf0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8d00: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8d10: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8d20: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8d30: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8d40: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8d50: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8d60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8d70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8d80: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8d90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8da0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8db0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8dc0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8de0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8df0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8e10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8e20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8e30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8e40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8e50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8e60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8e70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8e80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8e90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8ea0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8eb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8ec0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8ed0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8ee0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8ef0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8f00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8f10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8f20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8f30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8f40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8f50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8f60: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8f70: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8f80: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8f90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8fa0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8fc0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8fd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8fe0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ff0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
9000: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
9010: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
9020: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
9030: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9040: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
9050: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
9060: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
9070: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
9080: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
9090: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
90a0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
90b0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
90c0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
90d0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
90e0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
90f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9100: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9110: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9120: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9130: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9140: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9150: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9160: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9170: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9190: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
91a0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
91b0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
91c0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
91d0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
91e0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
91f0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9200: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9210: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
9220: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
9230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9240: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
9250: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
9260: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
9270: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9280: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9290: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
92a0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
92b0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
92c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
92d0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
92e0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
92f0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9300: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9310: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9320: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9330: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9340: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9350: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9360: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9370: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9390: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
93a0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
93b0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
93c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
93d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
93e0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
93f0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9400: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9410: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9420: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9430: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9450: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9480: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9490: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
94a0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
94b0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
94c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
94d0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
94e0: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
94f0: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9500: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9510: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
9520: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
9530: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9540: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9550: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9570: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9590: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
95a0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
95b0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
95c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
95d0: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
95e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
95f0: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9600: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9610: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9620: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9630: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9640: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9650: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9660: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
9670: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9680: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9690: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
96a0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
96b0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
96c0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
96d0: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
96e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
96f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9710: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9720: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9730: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9740: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9750: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9760: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
9770: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9780: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9790: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
97a0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
97b0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
97c0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
97d0: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
97e0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
97f0: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9800: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9810: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9820: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9830: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9840: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9850: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
9870: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9880: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9890: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
98a0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
98b0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
98c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
98d0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
98e0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
98f0: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9900: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9910: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9920: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9930: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9940: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9950: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9960: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9970: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9980: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9990: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
99a0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
99b0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
99c0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
99d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
99e0: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
99f0: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9a00: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9a10: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9a20: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9a30: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9a40: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9a50: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9a60: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9a70: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9a80: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9a90: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9aa0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9ab0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9ac0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9ad0: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9ae0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9af0: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9b00: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9b10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b20: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9b30: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9b50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9b70: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9b80: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9b90: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9ba0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9bb0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9bc0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9bd0: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9be0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9bf0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9c00: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9c10: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9c20: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9c30: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9c40: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9c50: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9c60: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9c70: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9c80: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9c90: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9ca0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9cb0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9cc0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9cd0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9ce0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9cf0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9d00: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9d10: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9d20: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9d30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9d40: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9d50: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9d60: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9d70: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9d80: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9d90: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9da0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9db0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9dc0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9dd0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9de0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9df0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9e00: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9e10: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9e20: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9e30: 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20  eger is the new 
9e40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9e50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9e60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9e70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9e80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9e90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9ea0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9eb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9ec0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9ed0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9ee0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9ef0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9f00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9f10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9f20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9f30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9f40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9f50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9f60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9f70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9f80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9f90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9fa0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9fb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9fc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9fd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9fe0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
9ff0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
a000: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
a010: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
a020: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
a030: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a040: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
a050: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
a060: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
a070: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
a080: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
a090: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
a0a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
a0b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
a0c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a0d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
a0e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
a0f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
a100: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
a110: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
a120: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
a130: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
a140: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
a150: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
a160: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
a170: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
a180: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
a190: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
a1a0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
a1b0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
a1c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a1d0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
a1e0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
a1f0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
a200: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
a210: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a230: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a240: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a250: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a260: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a270: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a280: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a290: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a2a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a2b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a2c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a310: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a320: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a330: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a350: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a370: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a390: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a3a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a3b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a3c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a3d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a3e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a3f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a410: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a420: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a430: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a440: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a450: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a460: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a480: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a490: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a4a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a4b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a4c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a4d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a4e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a4f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a500: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a510: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a520: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a530: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a540: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a550: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a560: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a580: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a5a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a5b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a5c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a5d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a5e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a5f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a600: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a610: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a620: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a630: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a640: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a650: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a660: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a670: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a680: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a690: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a6a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a6b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a6c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a6d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a6e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a6f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a700: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a710: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a720: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a730: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a740: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a750: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a760: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a770: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a780: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a790: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a7a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a7b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a7c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a7d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a7e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a7f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a800: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a810: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a820: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a830: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a840: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a850: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a860: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a870: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a880: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a890: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a8a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a8b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a8c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a8e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a8f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a900: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a920: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a930: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a940: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a950: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a960: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a980: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
a990: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a9a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
a9b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
a9c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
a9d0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
a9e0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
a9f0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
aa00: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
aa10: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
aa20: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
aa30: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa40: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
aa50: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
aa60: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
aa70: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
aa80: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
aa90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aaa0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
aab0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
aac0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
aad0: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
aae0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
aaf0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
ab00: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
ab10: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ab30: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
ab40: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
ab50: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
ab60: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
ab70: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
ab80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
ab90: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
aba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
abb0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
abc0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
abd0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
abe0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
abf0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
ac00: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
ac10: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
ac20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
ac40: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
ac50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
ac60: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
ac70: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
ac80: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
ac90: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
aca0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
acb0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
acc0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
acd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
ace0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
acf0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ad00: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ad10: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
ad20: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ad30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad40: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
ad50: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
ad60: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
ad70: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
ad80: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
ad90: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
ada0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
adb0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
adc0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
add0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
ade0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
adf0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ae00: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ae10: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ae20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ae30: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ae40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae60: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ae70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ae80: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ae90: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
aea0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
aeb0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
aec0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
aed0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aee0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
aef0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
af00: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
af10: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
af20: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
af30: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
af40: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
af50: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
af60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
af70: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
af80: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
af90: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
afa0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
afb0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
afc0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
afd0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
afe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aff0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b000: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
b010: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
b020: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
b030: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
b040: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
b050: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
b060: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
b070: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
b080: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
b090: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
b0a0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
b0b0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
b0c0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
b0d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b0e0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b0f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
b100: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
b110: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
b120: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
b130: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
b140: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
b150: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
b160: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
b170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b180: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b190: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b1b0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
b1c0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
b1d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
b1e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
b1f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
b200: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
b210: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
b220: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
b230: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
b240: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
b250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
b260: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
b270: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
b280: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
b290: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
b2a0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
b2b0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
b2c0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
b2d0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
b2e0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
b2f0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
b300: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
b310: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
b320: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
b330: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
b340: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
b350: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
b360: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
b370: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
b380: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
b390: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
b3a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
b3b0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
b3c0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
b3d0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
b3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
b3f0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
b400: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
b410: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
b420: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
b430: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b440: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b450: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
b460: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
b470: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b480: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
b490: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
b4a0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
b4b0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
b4c0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
b4d0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
b4e0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
b4f0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
b500: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
b510: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
b520: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
b530: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
b540: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
b550: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
b560: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
b570: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
b580: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
b590: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
b5a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
b5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
b5c0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
b5d0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
b5e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
b5f0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
b600: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
b610: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
b620: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b630: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b640: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b650: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b660: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b670: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
b680: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
b690: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b6a0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
b6b0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
b6c0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
b6d0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b6e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b6f0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
b700: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
b710: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
b720: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
b730: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
b740: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
b750: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
b760: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
b770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
b780: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
b790: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
b7a0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
b7b0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
b7c0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
b7d0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
b7e0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
b7f0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
b800: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
b810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b820: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
b830: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
b840: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
b850: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
b860: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
b870: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
b880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b890: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
b8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b8b0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
b8c0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
b8d0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
b8e0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
b8f0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
b900: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
b910: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
b920: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
b930: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
b940: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
b950: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
b960: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
b970: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b980: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
b990: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
b9a0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
b9b0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
b9c0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
b9d0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
b9e0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b9f0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
ba00: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
ba10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ba20: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
ba30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ba40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
ba50: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
ba60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
ba70: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
ba80: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
ba90: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
baa0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
bab0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
bac0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
bad0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
bae0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
baf0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
bb00: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
bb10: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
bb20: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
bb30: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
bb40: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
bb50: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bb60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bb70: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bb80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bb90: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bba0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
bbb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
bbc0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
bbd0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bbe0: 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
bbf0: 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65  th a file handle
bc00: 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20  .  This file.** 
bc10: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
bc20: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
bc30: 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  as a pointer to 
bc40: 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  a native file ha
bc50: 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74  ndle and.** writ
bc60: 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  es the resulting
bc70: 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a   value there..**
bc80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bc90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bca0: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
bcb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
bcc0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bcd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
bce0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
bcf0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
bd00: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
bd10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
bd20: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
bd30: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
bd40: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
bd50: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
bd60: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
bd70: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
bd80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
bd90: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
bda0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
bdb0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
bdc0: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
bdd0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bde0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bdf0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
be10: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
be20: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
be30: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
be40: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
be50: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
be60: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
be70: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
be80: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
be90: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
bea0: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
beb0: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
bec0: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
bed0: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
bee0: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
bef0: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
bf00: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
bf10: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
bf20: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
bf30: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
bf40: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
bf50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bf60: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
bf70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bf80: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
bf90: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
bfa0: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
bfb0: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
bfc0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
bfd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
bfe0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
bff0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
c010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c020: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
c030: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c040: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
c050: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
c060: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
c070: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
c080: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
c090: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c0a0: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
c0b0: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
c0c0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c0e0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
c0f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c110: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c120: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c140: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c150: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c170: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
c1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
c200: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
c230: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
c260: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
c290: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
c2c0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
c2f0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c310: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c320: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
c340: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
c350: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
c370: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
c380: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
c3a0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
c3b0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
c3d0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
c3e0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
c3f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c410: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
c420: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
c430: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
c440: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
c450: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
c460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
c470: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c480: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
c490: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
c4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c4c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
c4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c4e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
c4f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
c500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c510: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
c520: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
c530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c540: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
c550: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
c560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c570: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
c580: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
c590: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c5a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
c5b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
c5c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c5d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c5e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
c5f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c600: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
c610: 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70        30../* dep
c620: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c640: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c650: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c660: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c670: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c680: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c690: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c6a0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c6b0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c6c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c6d0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c6e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c6f0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c700: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c710: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c720: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c730: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c740: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c750: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c760: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c770: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c780: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c790: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c7a0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c7b0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c7c0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c7d0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c7e0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c7f0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c810: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c820: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c830: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c840: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c850: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c860: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c870: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c890: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
c8a0: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
c8b0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
c8c0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
c8d0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
c8e0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
c8f0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
c900: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
c910: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
c920: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
c930: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
c940: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
c950: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
c960: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
c970: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
c980: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
c990: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
c9a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c9b0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
c9c0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c9d0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
c9e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c9f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
ca00: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
ca10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ca20: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
ca30: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
ca40: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
ca50: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
ca60: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
ca70: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
ca80: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
ca90: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
caa0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
cab0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
cac0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
cad0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
cae0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
caf0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
cb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
cb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
cb20: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
cb30: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
cb40: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
cb50: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
cb60: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
cb70: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
cb80: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
cb90: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
cba0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
cbb0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
cbc0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
cbd0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
cbe0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
cbf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
cc00: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
cc10: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
cc20: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
cc30: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
cc40: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
cc50: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
cc60: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
cc70: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
cc80: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
cc90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
cca0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
ccb0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
ccc0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
ccd0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
cce0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
ccf0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
cd00: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
cd10: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
cd20: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
cd30: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
cd40: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
cd50: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
cd60: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
cd70: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
cd80: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
cd90: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
cda0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
cdb0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
cdc0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
cdd0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
cde0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
cdf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ce00: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
ce10: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
ce20: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
ce30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ce40: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
ce50: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
ce60: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
ce70: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ce80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ce90: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
cea0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ceb0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
cec0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ced0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
cee0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
cef0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
cf00: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
cf10: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
cf20: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
cf30: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
cf40: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cf50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
cf60: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
cf70: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
cf80: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
cf90: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
cfa0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
cfb0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
cfc0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
cfd0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
cfe0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
cff0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
d000: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
d010: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
d020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
d030: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
d040: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
d050: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
d060: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d070: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
d080: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
d090: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
d0a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
d0b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
d0c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
d0d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
d0e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
d0f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
d100: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d110: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
d120: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
d130: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
d140: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
d150: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
d160: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
d170: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
d180: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
d190: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
d1a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
d1b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
d1c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
d1d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
d1e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
d1f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d200: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
d210: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
d220: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
d230: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
d240: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
d250: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
d260: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
d270: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
d280: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
d290: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
d2a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d2b0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
d2c0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
d2d0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
d2e0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
d2f0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
d300: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
d310: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
d320: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
d330: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
d340: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
d350: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
d360: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
d370: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
d380: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d390: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
d3a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d3b0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
d3c0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
d3d0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
d3e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d3f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
d400: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
d410: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
d420: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
d430: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
d440: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
d450: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
d460: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
d470: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
d480: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
d490: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
d4a0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
d4b0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
d4c0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
d4d0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d4e0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
d4f0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
d500: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
d510: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
d520: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
d530: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
d540: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
d550: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
d560: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
d570: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
d580: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
d590: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
d5a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
d5b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
d5d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d5e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d5f0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
d630: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
d640: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d650: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
d660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d670: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
d680: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
d6a0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
d6b0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
d6c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
d6d0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
d6e0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
d6f0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
d700: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
d710: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
d720: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
d730: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
d740: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
d750: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
d760: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
d770: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
d780: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
d790: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
d7a0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
d7b0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d7c0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d7d0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d7e0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d7f0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d810: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d820: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d830: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d840: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d850: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d860: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d870: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d880: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d890: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d8a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d8b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d8c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d8d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d8e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d8f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d900: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d910: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d930: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d940: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d950: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d960: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d980: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d990: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d9a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d9b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d9c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d9d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d9e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d9f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
da00: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
da10: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
da20: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
da30: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
da40: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
da50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da60: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
da70: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
da80: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
da90: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
daa0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
dab0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
dac0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
dad0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
dae0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
daf0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
db00: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
db10: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
db20: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
db30: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
db40: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
db50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
db60: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
db70: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
db80: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
db90: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
dba0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
dbb0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
dbc0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
dbd0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
dbe0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
dbf0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
dc00: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
dc10: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
dc20: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
dc30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
dc40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
dc50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
dc60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
dc70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
dc80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
dc90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
dca0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
dcb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
dcc0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
dcd0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
dce0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
dcf0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
dd00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
dd10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
dd20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
dd40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dd50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
dd60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
dd70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
dd80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
dd90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
dda0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
ddb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
ddc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
ddd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
dde0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
ddf0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
de00: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
de10: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
de20: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
de30: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
de40: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
de50: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
de60: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
de70: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
de80: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
de90: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
deb0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
dec0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ded0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
dee0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
def0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
df00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
df10: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
df20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
df30: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
df40: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
df50: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
df60: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
df70: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
df80: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
df90: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
dfa0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
dfb0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
dfc0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
dfd0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
dfe0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
dff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
e000: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
e010: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
e020: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
e030: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
e040: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
e050: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
e060: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e070: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
e080: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
e090: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
e0a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
e0b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
e0c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
e0d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
e0e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
e0f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
e100: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
e110: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
e120: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
e130: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
e140: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
e150: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e160: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
e170: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
e180: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
e190: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
e1a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
e1b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
e1c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
e1d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
e1e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
e1f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
e200: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
e210: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
e220: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
e230: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
e240: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
e250: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
e260: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
e270: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
e280: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
e290: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
e2a0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
e2b0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
e2c0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
e2d0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
e2e0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
e2f0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
e300: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
e310: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
e320: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
e330: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e340: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
e350: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
e360: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
e370: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
e380: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
e390: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
e3a0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
e3b0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e3c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
e3d0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
e3e0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
e3f0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
e400: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
e410: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
e420: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
e430: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
e440: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
e450: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
e460: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e470: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
e480: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
e490: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
e4a0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
e4b0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
e4c0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
e4d0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
e4e0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
e4f0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
e500: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
e510: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
e520: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
e530: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
e540: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
e550: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
e560: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
e570: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
e580: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
e590: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
e5a0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
e5b0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e5c0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
e5d0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
e5e0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
e5f0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
e600: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
e610: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
e620: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
e630: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
e640: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
e650: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
e660: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
e670: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
e680: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
e690: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
e6a0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
e6b0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
e6c0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
e6d0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
e6e0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
e6f0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
e700: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
e710: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
e720: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
e730: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
e740: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
e750: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
e760: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e770: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
e780: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
e790: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
e7a0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
e7b0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e7c0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e7d0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e7e0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e7f0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e800: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e810: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e820: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e830: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e840: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e850: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e860: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e870: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e880: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e890: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e8a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e8b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e8c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e8d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e8e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e8f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e900: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e910: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e920: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e930: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e940: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e950: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e960: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e970: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e980: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e990: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e9a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e9c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e9d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e9e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e9f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ea00: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ea10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ea20: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ea30: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ea40: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ea50: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ea60: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
ea70: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
ea80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ea90: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
eaa0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
eab0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
eac0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
ead0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
eae0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
eaf0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb00: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
eb10: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
eb20: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
eb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
eb40: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
eb50: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
eb60: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
eb70: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
eb80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb90: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
eba0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
ebb0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
ebc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
ebe0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
ebf0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
ec00: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ec10: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
ec20: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
ec30: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
ec40: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
ec50: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
ec60: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
ec70: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
ec80: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
ec90: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
eca0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
ecb0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ecc0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
ecd0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
ecf0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
ed00: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ed10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed20: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
ed30: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
ed40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed50: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
ed60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ed70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ed80: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
ed90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eda0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
edb0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
edc0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
edd0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
ede0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
edf0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
ee00: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
ee10: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
ee20: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
ee30: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ee40: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ee50: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
ee60: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ee70: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
ee80: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
ee90: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
eea0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
eeb0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
eec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eed0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eee0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
eef0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
ef00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
ef10: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
ef20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ef30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ef40: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
ef50: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
ef60: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ef70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ef80: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
ef90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
efa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
efb0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
efc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
efd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
efe0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
eff0: 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
f000: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
f010: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
f020: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
f030: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
f040: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
f050: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
f060: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f070: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
f080: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
f090: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
f0a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
f0b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
f0c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
f0d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
f0e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
f0f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
f100: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
f110: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
f120: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
f140: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
f150: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f160: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
f170: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
f180: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
f190: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
f1a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
f1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f1c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
f1d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f1e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
f200: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
f210: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
f220: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
f230: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
f240: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
f250: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
f260: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
f270: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
f280: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f290: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
f2a0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
f2b0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
f2c0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
f2d0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
f2e0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
f2f0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
f300: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
f310: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
f320: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f330: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
f340: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
f350: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f360: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f380: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
f390: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
f3a0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
f3b0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
f3c0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
f3d0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
f3e0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
f3f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f400: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
f410: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f420: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
f430: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
f440: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f450: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
f460: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f470: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
f480: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
f490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
f4a0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
f4b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f4c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f4d0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
f4e0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
f4f0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
f500: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
f510: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f520: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
f530: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
f540: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
f550: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
f560: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
f570: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
f580: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
f590: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
f5a0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f5b0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f5c0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f5d0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f5e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f5f0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
f600: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f610: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f620: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f630: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f640: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f650: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
f660: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
f670: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
f680: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
f690: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
f6a0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
f6b0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
f6c0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
f6d0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
f6e0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f6f0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
f700: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
f710: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
f720: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
f730: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
f740: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
f750: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f760: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
f770: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f790: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f7b0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f7c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f7d0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f7e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f7f0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f800: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f810: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f820: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f830: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f840: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f850: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f860: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f870: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f880: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f890: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f8a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f8b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f8c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f8d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f8e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f8f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f900: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f910: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f920: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f940: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f950: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f980: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f990: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f9a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f9b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f9c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f9d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f9e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f9f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
fa00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa10: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
fa20: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
fa30: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
fa40: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
fa50: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
fa60: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
fa70: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
fa80: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
fa90: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
faa0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
fab0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
fac0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
fad0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fae0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
faf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fb00: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fb10: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
fb20: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
fb30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb40: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fb50: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
fb60: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
fb70: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
fb80: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
fb90: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
fba0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
fbb0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
fbc0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
fbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
fbe0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
fbf0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
fc00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc10: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
fc20: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
fc30: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
fc40: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
fc50: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
fc60: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fc70: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
fc80: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fc90: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fca0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
fcb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcc0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
fcd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fce0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
fcf0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
fd00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd10: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
fd20: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
fd30: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
fd40: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
fd50: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fd60: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
fd70: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
fd80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
fd90: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
fda0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
fdb0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
fdc0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
fdd0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
fde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
fdf0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
fe00: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
fe10: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
fe20: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
fe30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fe40: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
fe50: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
fe60: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
fe70: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
fe80: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
fe90: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
fea0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
feb0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
fec0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
fed0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fee0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ff00: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ff10: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
ff20: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
ff30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
ff40: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ff50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ff60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
ff70: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ff80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
ff90: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
ffa0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
ffb0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
ffc0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
ffd0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
ffe0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
fff0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
10000 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
10010 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
10020 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
10030 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
10040 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
10050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
10060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
10070 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
10080 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
10090 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
100a0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
100b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
100c0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
100d0 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
100e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
100f0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10100 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10110 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
10120 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
10130 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
10140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10150 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
10160 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
10170 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
10180 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
10190 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
101a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
101b0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
101c0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
101d0 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
101e0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
101f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
10200 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
10210 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
10220 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
10230 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
10240 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
10250 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10260 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
10270 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
10280 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
10290 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
102a0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
102b0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
102c0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
102d0 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
102e0 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
102f0 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
10300 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
10310 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
10320 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
10330 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
10340 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
10350 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10360 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10370 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
10380 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
10390 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
103a0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
103b0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
103c0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
103d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
103f0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
10400 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
10410 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
10420 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
10430 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10440 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
10450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10460 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
10470 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
10480 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
10490 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
104a0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
104b0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
104c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
104d0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
104e0 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
104f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10500 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
10510 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
10520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
10530 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
10540 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
10550 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
10560 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
10570 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
10580 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
10590 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
105a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
105b0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
105c0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
105d0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
105e0 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
105f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
10600 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
10610 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
10620 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
10630 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10640 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
10650 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
10660 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
10670 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
10680 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
106a0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
106b0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
106c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
106d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
106e0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
106f0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
10700 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
10710 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10720 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
10730 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10740 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
10750 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10760 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
10770 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10780 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10790 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
107a0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
107b0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
107c0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
107d0 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
107e0 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
107f0 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10800 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10810 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10820 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10830 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10840 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10850 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10860 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10870 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10880 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10890 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
108a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
108b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
108c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
108d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
108e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
108f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10900 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10910 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10920 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10930 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10940 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10960 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10970 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10980 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10990 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
109a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
109b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
109c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
109d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
109e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
109f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10a00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10a10 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10a20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10a40 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10a50 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10a60 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10a70 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10a80 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10a90 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10aa0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10ab0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10ac0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10ad0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10ae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10af0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10b00 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10b10 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10b20 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10b30 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10b40 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10b50 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
10b60 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10b70 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
10b80 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
10b90 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
10ba0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
10bb0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10bc0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10bd0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10be0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10c00 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10c10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10c30 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10c40 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10c50 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
10c60 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
10c70 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
10c80 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
10c90 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
10ca0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10cb0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10cc0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10cd0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10ce0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cf0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10d00 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10d10 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10d20 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10d30 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10d40 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10d50 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
10d60 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
10d70 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
10d80 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10d90 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
10da0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
10db0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10dc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10de0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10df0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10e00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e10 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10e20 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10e30 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10e40 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10e50 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10e60 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10e70 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10e80 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10e90 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
10ea0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10ec0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10ed0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ef0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10f00 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10f10 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10f20 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10f30 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10f40 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10f50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10f60 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10f90 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10fb0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10fd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10fe0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10ff0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11000 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11010 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
11020 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
11030 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
11040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
11050 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
11060 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
11070 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11080 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
11090 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
110a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
110b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
110c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
110d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
110e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
110f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
11110 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
11120 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
11130 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11140 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
11150 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
11160 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
11170 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
11180 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
11190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
111a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
111b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
111c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
111d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
111e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
111f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
11210 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
11220 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
11230 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
11240 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
11250 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
11260 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
11270 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
11280 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
11290 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
112a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
112b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
112c0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
112d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
112e0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
112f0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11300 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
11310 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
11320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11330 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
11340 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
11350 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
11360 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
11370 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11380 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
11390 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
113a0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
113b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
113c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
113d0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
113e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
113f0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11400 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
11410 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
11420 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
11430 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
11440 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11450 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
11460 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
11480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11490 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
114a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
114b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
114c0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
114d0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
114e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
114f0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11500 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11510 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11520 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11530 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11540 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11550 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11560 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
11570 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
11580 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
11590 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
115a0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
115b0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
115c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
115d0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
115e0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
115f0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11600 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11610 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11620 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11630 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11640 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11650 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11660 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
11670 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
11680 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
11690 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
116a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
116b0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
116c0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
116d0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
116e0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
116f0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11700 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11710 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11720 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11740 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11750 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11760 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
11770 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
11780 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
11790 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
117a0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
117b0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
117c0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
117d0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
117e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
117f0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11800 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11810 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11820 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11830 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11840 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11850 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11860 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11870 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
11880 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
11890 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
118a0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
118b0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
118c0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
118d0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
118e0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
118f0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11910 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11920 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11930 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11940 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11950 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11960 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11970 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11980 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11990 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
119a0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
119b0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
119c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
119d0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
119e0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
119f0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11a00 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11a10 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11a20 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11a40 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11a50 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11a60 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11a70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11a80 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11a90 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
11aa0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
11ab0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11ac0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11ad0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11ae0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11af0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11b00 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11b10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11b20 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11b30 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11b40 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11b50 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11b60 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11b70 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11b80 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11b90 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11ba0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
11bb0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11bc0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11bd0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11be0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11bf0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11c00 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11c10 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11c20 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11c30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11c40 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11c50 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11c60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11c70 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11c80 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11c90 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
11ca0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
11cb0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11cc0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11cd0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11ce0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11cf0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11d00 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11d10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11d20 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11d30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11d40 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11d50 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11d60 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11d70 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11d80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11d90 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
11da0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
11db0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11dc0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11dd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11de0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11df0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11e00 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11e10 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11e20 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11e30 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11e40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11e60 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11e70 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11e80 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11e90 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11ea0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11eb0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11ec0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11ed0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11ee0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11ef0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11f00 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11f10 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11f20 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11f30 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11f40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11f50 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f60 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11f70 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11f80 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11f90 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11fa0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11fb0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11fd0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11fe0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11ff0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12000 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
12010 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
12020 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
12030 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
12040 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
12050 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12060 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
12070 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
12080 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
12090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
120a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
120b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
120c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
120d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
120e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
120f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12100 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12110 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
12120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12130 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
12140 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
12150 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
12160 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12170 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12180 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
12190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
121a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
121b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
121c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
121e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
121f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12200 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
12210 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
12220 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12230 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12240 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12250 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12260 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12270 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
12280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
122b0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
122c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
122d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
122e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
122f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12300 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
12310 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
12320 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
12330 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
12340 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
12350 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
12360 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
12370 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
12380 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
12390 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
123a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
123b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
123c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
123d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
123e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
123f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
12410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
12420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
12430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
12440 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12450 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12470 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12480 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12490 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
124a0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
124b0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
124c0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
124d0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
124e0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
124f0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12500 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12510 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12520 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12530 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12540 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12550 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12560 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12570 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12580 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12590 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
125a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
125b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
125c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
125d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
125e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
125f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12600 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12610 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12620 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12630 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12640 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12650 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12660 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12670 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12680 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12690 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
126a0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
126b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
126c0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
126e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
126f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12700 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12710 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12720 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12730 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12740 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12750 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12760 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12770 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12780 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
12790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
127a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
127b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
127c0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
127d0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
127e0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
127f0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12800 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12810 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12830 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12840 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12850 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12860 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12870 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
12880 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
12890 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
128a0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
128b0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
128c0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
128d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
128e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
128f0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12900 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12910 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12920 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12930 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12940 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12950 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12960 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12970 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12980 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12990 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
129a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
129b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
129c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
129d0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
129e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12a00 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12a10 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12a30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12a40 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12a50 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12a70 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12a80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12a90 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12aa0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12ab0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12ac0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12ad0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12ae0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12af0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12b00 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12b10 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12b20 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12b40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12b50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12b60 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12b70 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12b80 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12b90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12ba0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
12bb0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12bc0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12bd0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12be0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12bf0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12c00 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12c20 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12c30 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12c40 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12c50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12c70 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12c90 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
12ca0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
12cb0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12cc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12cd0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12ce0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12cf0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12d00 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12d10 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12d20 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12d30 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12d40 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12d50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12d70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12d80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12d90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12da0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12db0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12dc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12dd0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12de0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12df0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e10 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e20 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12e40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12e50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e60 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12e70 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12e80 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12e90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12ea0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12eb0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12ec0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12ed0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12ef0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f00 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12f20 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12f40 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12f50 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12f60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12f70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12f80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12f90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12fa0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fc0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12fd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12ff0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
13000 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13010 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13020 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
13040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13050 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13060 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
13070 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13080 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13090 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
130a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
130b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
130c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
130d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
130e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
130f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13100 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13110 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13120 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13130 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13140 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13150 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13160 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13170 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
13180 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
13190 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
131a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
131b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
131c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
131d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
131e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
131f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13200 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13210 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13230 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
13240 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13250 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13260 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
13270 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
13280 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
13290 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
132a0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
132b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
132c0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
132d0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
132e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
132f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
13300 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
13310 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13320 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13330 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13340 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13350 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13360 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13380 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
13390 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
133a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
133b0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
133c0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
133d0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
133e0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
133f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13400 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
13410 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
13420 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
13430 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13440 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
13450 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
13460 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
13470 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
13480 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
13490 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
134a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
134c0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
134d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
134e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
134f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13500 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
13510 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13520 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13530 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13540 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
13550 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
13560 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13570 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
13580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13590 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
135a0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
135b0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
135c0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
135d0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
135e0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
135f0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
13600 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
13620 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
13630 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
13660 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13670 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
13680 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
13690 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
136a0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
136b0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
136c0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
136d0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
136e0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
136f0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
13700 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
13710 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13720 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
13730 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13740 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13750 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13760 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
13770 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
13780 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
13790 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
137a0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
137b0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
137c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
137d0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
137e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
137f0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13800 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13810 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13820 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13830 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13840 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13860 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
13870 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
13880 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
13890 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
138a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
138b0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
138c0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
138d0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
138e0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
138f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13900 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13910 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13920 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13930 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13940 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13950 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13960 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
13970 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13980 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
13990 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
139c0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
139d0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
139e0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
139f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13a00 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13a10 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13a20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13a30 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13a50 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
13a60 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
13a70 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
13a80 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13a90 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
13aa0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13ab0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13ac0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13ad0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13ae0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13af0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13b00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13b10 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13b20 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13b30 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13b40 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13b50 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
13b60 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
13b70 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
13b80 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13b90 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13ba0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13bb0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13bc0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13bd0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13be0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13bf0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13c00 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13c10 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13c20 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13c30 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13c40 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13c50 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13c60 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
13c70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13c80 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
13c90 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13ca0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13cb0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13cc0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13cd0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13ce0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13cf0 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13d10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13d20 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13d30 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13d40 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13d50 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
13d60 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
13d70 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
13d80 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
13d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
13da0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
13db0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13dc0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13dd0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13de0 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13df0 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13e00 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13e20 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13e30 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13e40 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13e50 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
13e60 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
13e70 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
13e80 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
13e90 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
13ea0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13eb0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13ed0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
13ee0 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
13ef0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13f00 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
13f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
13f20 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
13f30 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
13f40 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
13f50 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
13f60 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
13f70 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
13f80 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
13f90 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
13fa0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
13fb0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13fc0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
13fd0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
13fe0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
13ff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14000 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14010 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14020 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14030 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14050 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14060 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14070 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14080 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14090 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
140a0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
140b0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
140c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
140d0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
140e0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
140f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14100 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14110 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14130 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
14140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14150 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14170 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
14180 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14190 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
141a0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
141b0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
141c0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
141d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141e0 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
141f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14200 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
14210 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
14220 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14230 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14240 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
14250 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14260 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
14270 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
14280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14290 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
142a0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
142b0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
142c0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
142d0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
142e0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
142f0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
14300 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
14310 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
14320 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14330 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14340 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14360 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
14370 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
14380 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
14390 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
143a0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
143b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
143c0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
143d0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
143e0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
143f0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
14400 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
14410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14420 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
14430 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14440 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14450 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
14460 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
14470 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
14480 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14490 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
144a0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
144b0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
144c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
144d0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
144e0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
144f0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14500 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14510 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
14520 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
14530 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14540 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14560 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
14570 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14590 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
145a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
145b0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
145c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
145d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
145e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
145f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14600 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14610 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
14620 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14630 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
14640 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
14650 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
14660 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14670 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
14680 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14690 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
146a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
146b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
146c0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
146d0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
146e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
146f0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
14700 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14710 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14720 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14730 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14740 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14750 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14760 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14770 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14780 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14790 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
147a0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
147b0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
147c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
147d0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
147e0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
147f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14800 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14810 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14830 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14840 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14850 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
14860 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14880 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
14890 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
148a0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
148b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
148c0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
148d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
148e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148f0 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14920 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14930 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14940 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14950 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14960 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14970 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14980 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
14990 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
149a0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
149b0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
149c0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
149d0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
149e0 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
149f0 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14a00 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14a10 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14a20 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14a30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14a40 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14a50 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14a60 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14a70 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14a80 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14a90 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14aa0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14ab0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14ac0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14ad0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14af0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14b00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14b10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14b20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14b50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14b60 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14b70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14ba0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14bb0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14bc0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14bd0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14be0 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14bf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14c00 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14c10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14c20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14c30 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14c40 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14c50 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
14c60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
14c70 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
14c80 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14c90 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14cc0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14cd0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14ce0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14cf0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d00 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14d10 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14d20 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14d30 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14d40 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14d50 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
14d60 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
14d70 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
14d80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14d90 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14da0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14db0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14dc0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14dd0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14de0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14df0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14e00 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14e20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14e30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14e40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14e50 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
14e60 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
14e70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
14e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14e90 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14eb0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14ec0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14ed0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ef0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14f00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14f10 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14f20 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14f30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f50 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f60 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14f70 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14f80 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14f90 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
14fa0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
14fb0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14fc0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14fd0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
14fe0 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
14ff0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15000 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15010 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15020 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15030 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15040 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15050 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15060 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
15070 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
15080 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
15090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
150b0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
150c0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
150d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
150e0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
150f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15100 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15110 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15120 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15130 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15140 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15150 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15160 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15170 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
15180 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
15190 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
151a0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
151b0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
151c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
151d0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
151e0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
151f0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
15200 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
15210 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
15220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15230 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
15240 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
15250 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15270 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15280 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
15290 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
152a0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
152b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152c0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
152d0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
152e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
152f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15300 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
15310 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15320 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
15330 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
15340 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
15350 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
15360 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
15370 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
15380 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
15390 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
153a0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
153b0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
153c0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
153d0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
153e0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
153f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
15400 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
15410 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15420 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
15430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15440 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
15450 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
15460 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
15470 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
15480 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
15490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
154a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
154b0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
154c0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
154d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
154e0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15500 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
15520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15540 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
15550 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
15560 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15570 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
15580 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
15590 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
155a0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
155b0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
155c0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
155d0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
155e0 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
155f0 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
15600 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
15610 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
15640 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
15650 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
15660 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
15670 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
15680 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
15690 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
156a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
156b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
156c0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
156d0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
156e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
156f0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
15700 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
15710 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
15720 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
15730 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15740 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
15750 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
15760 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
15770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15790 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
157a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
157b0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
157c0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
157d0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
157e0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
157f0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15800 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15810 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15830 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15840 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
15860 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15870 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
15880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15890 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
158a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
158b0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
158c0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
158d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
158e0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
158f0 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15900 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15910 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15920 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15930 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15940 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15950 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
15960 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
15970 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
15980 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
15990 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
159a0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
159b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
159c0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
159d0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
159e0 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
159f0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15a00 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15a10 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a20 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a30 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15a40 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15a50 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
15a60 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
15a70 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
15a80 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15a90 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15aa0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15ab0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15ac0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15ad0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15ae0 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15af0 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15b00 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15b10 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15b20 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15b30 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15b40 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15b50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b60 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b80 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15ba0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15bb0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15bc0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15bd0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15be0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15bf0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15c00 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15c10 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15c20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15c30 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15c40 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15c60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15c70 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
15c80 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15c90 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15ca0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15cb0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15cc0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15ce0 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15cf0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15d00 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15d10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15d20 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15d30 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15d40 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15d50 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
15d60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
15d70 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
15d80 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15d90 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15da0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15db0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15dc0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15dd0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15de0 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15df0 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15e00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15e10 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15e20 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15e30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15e40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15e60 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
15e70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e80 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15e90 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15ea0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15eb0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15ec0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15ed0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15ee0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15ef0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15f00 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15f10 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15f20 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
15f30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
15f40 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
15f50 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
15f60 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
15f70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f80 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
15f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
15fa0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
15fb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15fc0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
15fd0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
15fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
15ff0 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16000 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16010 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16020 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16030 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16040 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16050 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16060 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
16070 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
16080 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
16090 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
160a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
160b0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
160c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160d0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
160e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
160f0 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16100 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16110 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16120 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16130 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16140 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16160 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
16170 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
16180 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
16190 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
161a0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
161b0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
161c0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
161d0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
161e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
161f0 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
16200 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16210 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
16220 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
16230 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
16240 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
16250 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
16260 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16270 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
16280 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
16290 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
162a0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
162b0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
162c0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
162d0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
162e0 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
162f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
16300 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
16310 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
16320 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
16330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
16340 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
16350 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
16360 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
16370 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
16380 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
16390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
163a0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
163b0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
163c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163d0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
163e0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
163f0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16400 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
16410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16420 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16430 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
16440 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
16450 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
16460 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
16470 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
16480 2e 20 5e 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 20  _WIN32_HEAPSIZE 
164a0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
164b0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
164c0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
164d0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
164e0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
164f0 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
16500 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16510 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16520 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16530 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16540 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
16550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16560 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
16570 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16580 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16590 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
165a0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
165b0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
165c0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
165d0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
165e0 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
165f0 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
16600 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16620 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
16630 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
16640 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
16650 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
16660 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
16670 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
16680 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
16690 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
166a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
166b0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
166c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
166d0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
166e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
166f0 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
16700 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16710 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16720 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
16730 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
16740 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
16750 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
16760 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
16770 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
16780 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
16790 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
167a0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
167b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
167c0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
167d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
167e0 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
167f0 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16800 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16810 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16820 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16830 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16840 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16850 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
16860 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
16870 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
16880 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
16890 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
168a0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
168b0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
168c0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
168d0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
168e0 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
168f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16900 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16910 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
16920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16930 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
16940 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16950 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16960 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
16970 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16980 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
16990 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
169a0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
169b0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
169c0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
169d0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
169e0 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
169f0 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
16a00 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
16a10 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
16a20 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
16a30 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
16a40 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
16a50 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
16a60 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
16a70 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16a80 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
16a90 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
16aa0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
16ab0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
16ac0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
16ad0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
16ae0 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
16af0 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
16b00 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
16b10 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
16b20 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
16b30 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
16b40 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
16b50 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
16b60 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
16b70 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
16b80 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
16b90 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
16ba0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16bb0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16bc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16bd0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
16be0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bf0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16c00 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c20 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16c30 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c50 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16c60 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
16c70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
16c90 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
16ca0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16cd0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16cf0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16d00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16d10 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16d20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16d30 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16d40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16d50 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16d60 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16d70 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
16d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d90 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
16da0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16db0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16de0 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16df0 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16e10 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16e20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16e30 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e50 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16e60 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
16e70 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16e80 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
16e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
16ea0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16eb0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16ec0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16ed0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16ee0 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16ef0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16f10 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16f20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f40 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16f50 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
16f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f70 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
16f80 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
16f90 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16fb0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16fc0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fe0 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16ff0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17000 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17030 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17040 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17050 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17070 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
17080 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170a0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
170b0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
170c0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
170d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170e0 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
170f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17100 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17120 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17130 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17140 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17160 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17170 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
17180 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
17190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171a0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
171b0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
171c0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
171d0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
171e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
171f0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17200 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17210 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17220 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
17230 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
17240 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
17250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
17260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
17270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
17280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
172a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
172b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
172c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
172d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
172e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
172f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
17300 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
17310 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
17320 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
17330 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
17340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17350 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
17360 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
17370 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
17380 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
17390 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
173a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
173b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
173c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
173d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
173e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
173f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17400 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
17410 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
17420 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
17430 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
17440 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
17450 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
17460 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
17470 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
17480 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17490 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
174a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
174b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
174c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
174d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
174e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
174f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
17500 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
17510 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
17520 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17530 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
17540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
17550 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17560 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
17570 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
17580 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
17590 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
175a0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
175b0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
175c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
175d0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
175e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
175f0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
17600 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
17610 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
17620 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
17630 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
17640 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
17650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
17660 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
17670 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
17680 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
17690 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
176a0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
176b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
176c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
176d0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
176e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
176f0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
17700 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
17710 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
17720 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
17730 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
17740 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
17750 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
17760 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
17770 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
17780 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
17790 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
177a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
177b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
177c0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
177d0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
177e0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
177f0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
17800 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
17810 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
17820 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
17830 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
17840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17850 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
17860 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
17870 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
17880 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
17890 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
178a0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
178b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
178c0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
178d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
178e0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
178f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
17900 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
17910 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
17920 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
17930 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
17940 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
17950 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
17960 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
17970 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
17980 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
17990 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
179a0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
179b0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
179c0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
179d0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
179e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
179f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17a00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
17a10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17a20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17a30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17a40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
17a50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17a60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
17a70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17a80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17a90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17ac0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17ad0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17ae0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17af0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17b00 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17b10 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17b20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17b30 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17b40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17b50 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17b60 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17b70 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17b80 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17b90 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17ba0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
17bb0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17bc0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17bd0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17be0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17bf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17c00 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17c10 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17c20 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17c30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17c40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17c50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17c60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17c70 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17c80 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17c90 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17ca0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
17cb0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17cc0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17cd0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17ce0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17cf0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17d00 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17d10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17d20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17d30 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17d40 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17d50 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17d60 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17d70 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17d80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17da0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17db0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17dc0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17dd0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17de0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17df0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17e00 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17e10 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17e20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17e30 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17e50 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17e60 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17e70 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17e80 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17e90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17ea0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17eb0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
17ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17ed0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17ee0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17ef0 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
17f00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
17f10 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
17f20 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
17f30 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
17f40 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
17f50 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
17f60 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
17f70 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
17f80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17f90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17fa0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17fb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17fc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17fd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
17fe0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
17ff0 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
18000 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
18010 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
18020 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
18030 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
18040 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18050 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18060 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18070 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18090 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
180a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
180b0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
180c0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
180d0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
180e0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
180f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18100 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18110 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18120 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18130 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18140 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18150 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18160 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18170 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18180 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
18190 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
181a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
181b0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
181c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
181d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
181e0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
181f0 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
18200 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18210 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
18220 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18230 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
18250 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18260 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
18270 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
18280 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
18290 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
182a0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
182b0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
182c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
182d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
182e0 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
182f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18300 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
18310 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
18320 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
18330 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
18340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
18350 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
18360 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
18370 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
18380 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18390 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
183a0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
183b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
183c0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
183d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183e0 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
183f0 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
18400 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
18410 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
18420 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
18430 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
18440 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18450 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18460 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18470 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18480 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18490 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
184a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
184b0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
184c0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
184d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
184e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
184f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18500 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
18510 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18520 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
18530 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18540 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18550 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
18560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18570 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
18580 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
18590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
185a0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
185b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
185c0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
185d0 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
185e0 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
185f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18600 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
18610 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
18620 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
18630 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
18640 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
18650 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
18660 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
18670 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
18680 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
18690 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
186a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
186b0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
186c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
186d0 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
186e0 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
186f0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
18700 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
18710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18720 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
18730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18740 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18750 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
18760 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
18770 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
18780 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
18790 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
187a0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
187b0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
187c0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
187d0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
187e0 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
187f0 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
18800 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
18810 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
18820 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
18830 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
18840 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
18850 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
18860 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
18870 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
18880 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
18890 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
188a0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
188b0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
188c0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
188d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
188e0 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20  r - non-zero to 
188f0 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
18900 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
18910 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
18920 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
18930 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e   them. The secon
18940 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18960 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
18970 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
18980 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18990 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
189a0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
189b0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
189c0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
189d0 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
189e0 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
189f0 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18a00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18a10 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
18a20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28  G</dt>.** <dd>^(
18a30 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  The SQLITE_DBCON
18a40 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
18a50 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
18a60 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
18a70 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c  ** the [query pl
18a80 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20  anner stability 
18a90 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47  guarantee] (QPSG
18aa0 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53  ).  When the QPS
18ab0 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20  G is active,.** 
18ac0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
18ad0 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ry statement wil
18ae0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
18af0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
18b00 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
18b10 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e   values of [boun
18b20 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e  d parameters].)^
18b30 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c   The QPSG disabl
18b40 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70  es some query op
18b50 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74  timizations.** t
18b60 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20  hat look at the 
18b70 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20  values of bound 
18b80 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63  parameters, whic
18b90 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20  h can make some 
18ba0 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65  queries.** slowe
18bb0 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47  r.  But the QPSG
18bc0 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61   has the advanta
18bd0 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69  ge of more predi
18be0 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ctable behavior.
18bf0 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50    With.** the QP
18c00 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74  SG active, SQLit
18c10 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  e will always us
18c20 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79  e the same query
18c30 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65   plan in the fie
18c40 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65  ld as.** was use
18c50 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
18c60 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20   in the lab..** 
18c70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
18c80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
18c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
18ca0 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
18cb0 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
18cc0 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18ce0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
18cf0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
18d00 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
18d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d20 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18d30 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
18d40 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
18d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d60 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18d70 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
18d80 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
18d90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18db0 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
18dc0 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
18dd0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18de0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18df0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
18e00 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
18e10 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18e20 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18e30 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
18e40 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
18e50 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e70 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
18e80 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
18e90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
18ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18eb0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
18ec0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
18ed0 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
18ee0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
18ef0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
18f00 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
18f10 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
18f20 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
18f30 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
18f40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
18f50 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
18f60 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
18f70 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
18f80 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
18f90 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
18fa0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
18fb0 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
18fc0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18fd0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
18fe0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
18ff0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19000 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
19010 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
19020 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
19030 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
19040 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
19050 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
19060 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
19070 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
19080 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
19090 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
190a0 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
190b0 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
190c0 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
190d0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
190e0 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
190f0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
19100 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
19110 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
19120 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
19130 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
19140 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
19150 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
19160 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
19170 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
19180 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
19190 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
191a0 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
191b0 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
191c0 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
191d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
191e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
191f0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
19200 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75  ace usually retu
19210 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
19220 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  of.** the most r
19230 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
19240 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
19250 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
19260 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
19270 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
19280 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e  onnection D. ^In
19290 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
192a0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
192b0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63  s are not.** rec
192c0 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75  orded. ^If no su
192d0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
192e0 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
192f0 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f  bles have ever o
19300 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74  ccurred .** on t
19310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19320 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73  ection D, then s
19330 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19340 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
19350 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a  rns .** zero..**
19360 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62  .** As well as b
19370 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74  eing set automat
19380 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61  ically as rows a
19390 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
193a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
193b0 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  les, the value r
193c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
193d0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
193e0 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62  set explicitly b
193f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  y.** [sqlite3_se
19400 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
19410 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d  wid()].**.** Som
19420 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
19430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
19440 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20  may INSERT rows 
19450 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
19460 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  s as.** part of 
19470 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61  committing a tra
19480 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74  nsaction (e.g. t
19490 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63  o flush data acc
194a0 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f  umulated in memo
194b0 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20  ry.** to disk). 
194c0 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62  In this case sub
194d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
194e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
194f0 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a  eturn the rowid.
19500 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
19510 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61  th these interna
19520 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  l INSERT operati
19530 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73  ons, which leads
19540 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74   to .** unintuit
19550 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72  ive results. Vir
19560 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
19570 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20  mentations that 
19580 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69  do write to rowi
19590 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74  d.** tables in t
195a0 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69  his way can avoi
195b0 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62  d this problem b
195c0 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20  y restoring the 
195d0 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77  original .** row
195e0 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b  id value using [
195f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19600 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19610 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
19620 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f  g .** control to
19630 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a   the user..**.**
19640 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
19650 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
19660 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74  a trigger then t
19670 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
19680 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20   .** return the 
19690 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
196a0 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c  nserted row as l
196b0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
196c0 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e  er is .** runnin
196d0 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67  g. Once the trig
196e0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73  ger program ends
196f0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19700 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
19710 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
19720 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
19730 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
19740 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a  er was fired.)^.
19750 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
19760 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
19770 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
19780 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
19790 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
197a0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
197b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
197c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
197d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
197e0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
197f0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
19800 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
19810 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
19820 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
19830 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
19840 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
19850 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
19860 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
19870 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
19880 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
19890 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
198a0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
198b0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
198c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
198d0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
198e0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
198f0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
19900 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
19910 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
19920 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
19930 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
19940 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
19950 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
19960 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
19970 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
19980 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
19990 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
199a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
199b0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
199c0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
199d0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
199e0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
199f0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
19a00 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
19a10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
19a20 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
19a30 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
19a40 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
19a50 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
19a60 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
19a70 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19a80 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
19a90 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
19aa0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
19ab0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
19ac0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
19ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
19ae0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19af0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
19b00 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
19b10 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
19b20 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
19b30 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
19b40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19b50 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19b60 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
19b70 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
19b80 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
19b90 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
19ba0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
19bb0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
19bc0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
19bd0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19be0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19bf0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
19c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19c10 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73  Set the Last Ins
19c20 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e  ert Rowid value.
19c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19c40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
19c50 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19c60 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52  nsert_rowid(D, R
19c70 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20  ) method allows 
19c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c90 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61  to.** set the va
19ca0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19cb0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
19cc0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19cd0 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69  d(D) to R .** wi
19ce0 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20  thout inserting 
19cf0 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64  a row into the d
19d00 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64  atabase..*/.void
19d10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
19d20 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19d30 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f  qlite3*,sqlite3_
19d40 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
19d50 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
19d60 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
19d70 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
19d80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
19d90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
19da0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
19db0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
19dc0 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
19dd0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
19de0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
19df0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
19e00 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e10 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
19e20 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
19e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
19e40 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
19e50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
19e60 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
19e70 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
19e80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
19e90 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
19ea0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
19eb0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
19ec0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
19ed0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
19ee0 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
19ef0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19f00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19f10 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
19f20 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
19f30 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
19f40 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
19f50 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
19f60 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19f70 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
19f80 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
19f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
19fa0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
19fb0 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
19fc0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
19fd0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
19fe0 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
19ff0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
1a000 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
1a010 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
1a020 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
1a030 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a040 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
1a050 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
1a060 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a070 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
1a080 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
1a090 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
1a0a0 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
1a0b0 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
1a0c0 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
1a0d0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
1a0e0 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
1a0f0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
1a100 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a110 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
1a120 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
1a130 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a140 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
1a150 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
1a160 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
1a170 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
1a180 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a190 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
1a1a0 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
1a1b0 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
1a1c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a1d0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
1a1e0 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
1a1f0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1a200 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
1a210 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
1a220 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
1a230 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1a240 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
1a250 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a260 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
1a270 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1a280 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
1a290 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
1a2a0 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
1a2b0 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
1a2c0 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
1a2d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
1a2e0 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
1a2f0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
1a300 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
1a310 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
1a320 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a340 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1a350 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
1a360 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
1a370 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
1a380 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
1a390 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
1a3a0 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
1a3b0 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
1a3c0 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
1a3d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
1a3f0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
1a400 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
1a410 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
1a420 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
1a430 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
1a440 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1a450 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
1a470 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
1a480 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
1a490 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
1a4a0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a4b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1a4c0 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
1a4d0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
1a4e0 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
1a4f0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
1a500 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
1a510 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
1a520 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
1a530 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
1a540 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
1a550 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a560 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
1a570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a580 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
1a590 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1a5a0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1a5b0 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
1a5c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1a5d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1a5e0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
1a5f0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
1a600 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a610 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a620 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a630 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a640 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a650 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1a660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a670 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a680 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1a690 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1a6a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1a6b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1a6c0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1a6d0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a6e0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1a6f0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1a700 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a710 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1a730 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1a740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a750 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1a760 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1a770 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a780 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a790 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a7a0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
1a7b0 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
1a7c0 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
1a7d0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
1a7e0 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
1a7f0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
1a800 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
1a810 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
1a820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a830 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
1a840 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
1a850 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
1a860 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
1a870 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
1a880 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1a890 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1a8a0 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
1a8b0 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
1a8c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a8d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a8e0 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
1a8f0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
1a900 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
1a910 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
1a920 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
1a930 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
1a940 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
1a950 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
1a960 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1a970 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1a980 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1a990 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a9a0 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1a9b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1a9c0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1a9d0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1a9e0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a9f0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1aa00 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1aa10 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1aa20 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1aa30 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1aa40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1aa50 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1aa60 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1aa70 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1aa80 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1aa90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1aaa0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1aab0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1aac0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1aad0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1aae0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1aaf0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1ab00 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
1ab10 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1ab20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1ab30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1ab40 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
1ab50 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
1ab60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ab70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1ab80 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1ab90 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1aba0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1abb0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1abc0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1abd0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1abe0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1abf0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1ac00 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1ac10 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1ac20 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1ac30 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1ac40 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1ac50 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1ac60 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1ac70 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1ac80 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1ac90 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1aca0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1acb0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1acc0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1acd0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1ace0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1acf0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1ad00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1ad10 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1ad20 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1ad30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1ad40 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1ad50 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1ad60 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1ad70 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1ad80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ad90 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1ada0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1adb0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1adc0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1add0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1ade0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1adf0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1ae00 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1ae10 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1ae20 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1ae30 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1ae40 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1ae50 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1ae60 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1ae70 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1ae80 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1ae90 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1aea0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1aeb0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1aec0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1aed0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1aee0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1aef0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1af00 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1af10 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1af20 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1af30 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1af40 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1af50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1af60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1af70 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1af80 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1af90 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1afa0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1afb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1afc0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1afd0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1afe0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1aff0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1b000 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1b010 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1b020 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1b030 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1b040 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1b050 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1b060 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1b070 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1b080 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1b090 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1b0a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b0b0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1b0c0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1b0d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b0e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b0f0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1b100 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1b110 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1b120 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1b130 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b140 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1b150 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1b160 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1b170 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1b180 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1b190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b1a0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1b1b0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1b1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b1d0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b1e0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b1f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b200 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1b210 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1b220 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1b230 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b240 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1b250 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1b260 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1b270 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b280 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1b290 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1b2a0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1b2b0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1b2c0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1b2d0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1b2e0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1b2f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1b300 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1b310 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1b320 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1b330 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1b340 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1b350 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1b360 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1b370 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1b380 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1b390 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1b3a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b3b0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1b3c0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1b3d0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1b3e0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1b3f0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1b400 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1b410 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1b420 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1b430 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1b440 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1b450 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1b460 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1b470 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1b480 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1b490 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1b4a0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1b4b0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1b4c0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1b4d0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1b4e0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1b4f0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1b500 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1b510 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1b520 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1b530 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1b540 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1b550 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1b560 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1b570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b580 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1b590 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1b5a0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1b5b0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1b5c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1b5d0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1b5e0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1b5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1b600 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1b610 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1b620 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1b630 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1b640 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1b650 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1b660 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1b670 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1b680 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1b690 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b6a0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1b6b0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1b6c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b6d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1b6e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1b6f0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1b700 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1b710 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1b720 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1b730 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1b740 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1b750 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1b760 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b770 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1b780 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1b790 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1b7a0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1b7b0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1b7c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b7d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b7e0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1b7f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b800 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1b810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1b820 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b830 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1b840 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b850 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1b860 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1b870 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1b880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b890 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1b8a0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1b8b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1b8c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1b8d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b8e0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1b8f0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1b900 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1b910 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b920 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1b930 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1b940 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1b950 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b960 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1b970 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1b980 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1b990 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b9a0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1b9b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1b9c0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1b9d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1b9e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1b9f0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1ba00 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1ba10 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1ba20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1ba30 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1ba40 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1ba50 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1ba60 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1ba70 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ba80 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1ba90 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1baa0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1bab0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1bac0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1bad0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1bae0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1baf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1bb00 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1bb10 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1bb20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1bb30 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1bb40 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1bb50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1bb60 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1bb70 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1bb80 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1bb90 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1bba0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1bbb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1bbc0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1bbd0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1bbe0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1bbf0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1bc00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1bc10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1bc20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1bc30 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1bc40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1bc50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1bc60 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1bc70 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1bc80 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1bc90 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1bca0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1bcb0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1bcc0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1bcd0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1bce0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bcf0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1bd00 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1bd10 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1bd20 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1bd30 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1bd40 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1bd50 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1bd60 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1bd70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1bd80 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1bd90 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1bda0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1bdb0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1bdc0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1bdd0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1bde0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1bdf0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1be00 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1be10 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1be20 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1be30 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1be40 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1be50 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1be60 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1be70 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1be80 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1be90 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1bea0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1beb0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1bec0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1bed0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1bee0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1bef0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1bf00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1bf10 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1bf20 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1bf30 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1bf40 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1bf50 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1bf60 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1bf70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1bf80 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1bf90 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1bfa0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1bfb0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1bfc0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1bfd0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1bfe0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1bff0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1c000 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1c010 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c020 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1c030 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1c040 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1c050 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1c060 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c070 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1c080 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1c090 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1c0b0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1c0c0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1c0d0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1c0e0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1c0f0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1c100 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1c110 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1c120 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1c130 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c140 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1c150 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1c160 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1c170 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1c180 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1c190 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1c1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1c1c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1c1d0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1c1e0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1c1f0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1c200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1c210 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1c220 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1c230 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1c240 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1c250 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1c260 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1c270 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1c280 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1c290 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1c2a0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1c2b0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1c2c0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1c2d0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1c2e0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1c2f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1c300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1c310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1c320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1c330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1c340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c370 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1c380 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1c390 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1c3a0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1c3b0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1c3c0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1c3d0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1c3e0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1c3f0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1c400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c410 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1c420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c430 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1c440 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c450 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1c460 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c470 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76  qlite3*,int(*)(v
1c480 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29  oid*,int),void*)
1c490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c4a0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1c4b0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1c4c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1c4d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1c4e0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1c4f0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1c500 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1c510 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1c520 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1c530 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1c540 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1c550 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1c560 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1c570 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1c580 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c590 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c5a0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1c5b0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1c5c0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1c5d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c5e0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1c5f0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1c600 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1c610 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1c620 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1c630 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1c640 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1c650 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1c660 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1c670 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1c680 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1c690 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1c6a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1c6b0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1c6c0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1c6d0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1c6e0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1c6f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c700 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1c710 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1c720 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1c730 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1c740 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1c750 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1c760 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1c770 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1c780 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1c790 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1c7a0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1c7b0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1c7c0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1c7d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c7e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1c7f0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1c800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c810 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1c820 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1c830 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1c840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c850 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1c860 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1c870 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1c880 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1c890 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1c8a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1c8b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1c8c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1c8d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1c8e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1c8f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1c900 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1c910 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1c920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c930 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1c940 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1c950 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1c960 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1c970 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1c980 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1c990 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1c9a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1c9b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1c9c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1c9d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1c9e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1c9f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1ca00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1ca10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1ca20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1ca30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ca40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1ca50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1ca60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1ca70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1ca80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1ca90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1caa0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1cab0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1cac0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1cad0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1cae0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1caf0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1cb00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1cb10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cb20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1cb30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1cb40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1cb50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1cb60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1cb70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1cb80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1cb90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1cba0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1cbb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1cbc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1cbd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1cbe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1cbf0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1cc00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1cc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1cc20 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1cc30 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1cc40 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1cc50 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1cc60 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1cc70 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1cc80 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1cc90 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1cca0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ccb0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1ccc0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1ccd0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1cce0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1ccf0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1cd00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1cd10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1cd20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1cd30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1cd40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1cd50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1cd60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cd70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1cd80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1cd90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1cda0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1cdb0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1cdc0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1cdd0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1cde0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1cdf0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1ce00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ce10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1ce20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1ce30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1ce40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1ce50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1ce60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1ce70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1ce80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1ce90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1cea0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1ceb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1cec0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1ced0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1cee0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1cef0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1cf00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1cf10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1cf20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1cf30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1cf40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1cf60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cf70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1cf80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cf90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1cfa0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1cfb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1cfc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1cfd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1cfe0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1cff0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d000 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1d010 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d020 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1d030 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d040 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1d050 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1d060 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1d070 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1d080 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1d090 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d0a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1d0b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1d0c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1d0d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d0e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1d0f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1d100 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1d110 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1d120 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1d130 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1d140 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1d150 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d160 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1d170 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1d180 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1d190 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d1a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1d1b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1d1c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1d1d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1d1e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1d1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1d200 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1d210 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1d220 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1d230 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1d240 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1d250 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1d260 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1d270 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1d280 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d290 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1d2a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d2b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1d2c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1d2d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d2e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d2f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1d300 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1d310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d320 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1d330 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1d340 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1d350 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1d360 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1d370 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1d380 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1d390 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1d3a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1d3b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1d3c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1d3d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1d3e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1d3f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1d400 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1d410 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1d420 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1d430 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1d440 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1d460 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1d470 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d490 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1d4a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d4b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1d4c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1d4d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1d4e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1d4f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1d500 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1d510 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1d520 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1d530 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1d540 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1d550 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1d560 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d570 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1d580 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1d590 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1d5a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1d5b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1d5c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1d5d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1d5e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1d5f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1d600 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1d610 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1d620 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1d630 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1d640 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1d650 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d660 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1d670 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1d680 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1d690 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1d6a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d6b0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1d6c0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1d6d0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1d6e0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1d6f0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1d700 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1d710 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1d720 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1d730 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1d740 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1d750 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1d760 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d770 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1d780 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1d790 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1d7a0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1d7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1d7c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d7d0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1d7e0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1d7f0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1d800 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1d810 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1d820 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1d830 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1d840 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1d850 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1d860 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1d870 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1d880 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d890 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1d8a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1d8b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1d8c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1d8d0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1d8e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1d8f0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1d900 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1d910 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1d920 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1d930 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d940 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1d950 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1d960 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1d970 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1d980 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1d990 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1d9a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1d9b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d9c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1d9d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1d9e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1d9f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1da00 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1da10 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1da20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1da30 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1da40 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1da50 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1da60 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1da70 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1da80 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1da90 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1daa0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1dab0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1dac0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1dad0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1dae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1daf0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1db00 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1db10 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1db20 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1db30 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1db40 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1db50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1db60 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1db70 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1db80 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1db90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1dba0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1dbb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1dbc0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1dbd0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1dbe0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1dbf0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1dc00 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1dc10 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1dc20 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1dc30 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1dc40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1dc50 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1dc60 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1dc70 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1dc80 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1dc90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1dca0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1dcb0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1dcc0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1dcd0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1dce0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1dcf0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1dd00 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1dd10 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1dd20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1dd30 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1dd40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1dd50 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1dd60 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1dd70 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1dd80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dd90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1dda0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1ddb0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1ddc0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1ddd0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1dde0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1ddf0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1de00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1de10 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1de20 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1de30 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1de40 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1de50 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1de60 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1de70 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1de80 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1de90 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1dea0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1deb0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1dec0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1ded0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1dee0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1def0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1df00 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1df10 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1df20 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1df30 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1df40 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1df50 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1df60 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1df70 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1df80 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1df90 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1dfa0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1dfb0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1dfc0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1dfd0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1dfe0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1dff0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1e000 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1e010 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e020 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e030 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e040 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e050 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e060 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e070 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e080 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e090 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e0a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e0b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e0c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e0d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e0e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e0f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1e100 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e110 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e120 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e130 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e140 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e150 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1e160 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1e170 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1e180 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1e190 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1e1a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1e1b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1e1c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1e1d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e1e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e1f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e200 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1e210 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1e220 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e230 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e240 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1e250 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1e260 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1e270 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1e280 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1e290 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1e2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1e2c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1e2d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1e2e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1e2f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e300 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1e310 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1e320 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1e330 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1e340 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1e350 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1e360 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1e370 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e380 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1e390 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1e3a0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1e3b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1e3c0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1e3d0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1e3e0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1e3f0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1e400 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1e410 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1e420 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1e430 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1e440 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1e450 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1e460 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1e470 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1e480 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1e490 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1e4a0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1e4b0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1e4c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e4d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e4e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e4f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e500 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1e510 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e520 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e530 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e550 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e560 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e570 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1e580 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1e590 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1e5a0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1e5b0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1e5c0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1e5d0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1e5e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e5f0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1e600 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1e610 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1e620 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1e630 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1e640 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1e650 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1e660 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1e670 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1e680 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1e690 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1e6a0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1e6b0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1e6c0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1e6d0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1e6e0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1e6f0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1e700 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1e710 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1e720 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1e730 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1e740 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1e750 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1e760 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e770 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1e780 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1e790 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1e7a0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1e7b0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1e7c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1e7d0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1e7e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1e7f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1e800 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1e810 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1e820 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1e830 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1e840 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e850 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1e860 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1e870 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1e890 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e8a0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1e8b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e8c0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1e8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1e8e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1e8f0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1e900 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1e910 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1e920 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1e930 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1e940 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1e950 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1e960 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1e970 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1e980 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1e990 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1e9a0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1e9b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e9c0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1e9d0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1e9e0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1e9f0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1ea00 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1ea10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1ea20 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1ea30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1ea40 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1ea50 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1ea60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1ea70 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1ea80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1ea90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1eaa0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1eab0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1eac0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1ead0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1eae0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1eaf0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1eb00 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1eb10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1eb20 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1eb30 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1eb40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1eb50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1eb60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1eb70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1eb80 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1eb90 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1eba0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1ebb0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1ebc0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1ebd0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1ebe0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1ebf0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ec10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ec20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1ec30 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1ec40 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1ec50 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1ec60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ec70 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1ec80 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1ec90 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1eca0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1ecb0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1ecc0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1ecd0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ece0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ecf0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ed00 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ed10 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ed20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ed30 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1ed40 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1ed50 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1ed60 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1ed70 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1ed80 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1ed90 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1eda0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1edb0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1edc0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1edd0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ede0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1edf0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ee00 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ee10 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ee20 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ee30 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1ee40 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1ee50 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1ee60 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1ee70 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1ee80 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1ee90 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1eea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1eeb0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1eec0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1eed0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1eee0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1eef0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1ef00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1ef10 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1ef20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1ef30 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1ef40 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1ef50 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1ef60 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1ef70 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1ef80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ef90 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1efa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1efb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1efc0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1efd0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1efe0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1eff0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1f000 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1f010 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1f020 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1f030 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1f040 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1f050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f060 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1f070 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1f080 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1f090 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1f0a0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1f0b0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1f0c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1f0d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1f0e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1f0f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1f100 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1f110 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1f120 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1f130 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1f140 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f150 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1f160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1f170 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1f180 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f190 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1f1a0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1f1b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1f1c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f1d0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1f1e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f1f0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1f200 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1f210 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1f220 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1f230 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1f240 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1f250 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1f260 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1f270 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1f280 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1f290 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1f2a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1f2b0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1f2c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1f2d0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1f2e0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1f2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f300 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1f310 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1f320 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f330 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1f340 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1f350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1f360 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1f370 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1f380 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f390 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1f3a0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1f3b0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1f3c0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1f3d0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1f3e0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1f3f0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1f400 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f410 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1f420 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1f430 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1f440 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1f450 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1f460 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1f470 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1f480 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1f490 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1f4a0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1f4b0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1f4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1f4d0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1f4e0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1f4f0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1f500 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1f510 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1f520 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1f530 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1f540 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1f550 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f560 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1f570 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1f580 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1f590 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1f5a0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1f5b0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1f5c0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1f5d0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1f5e0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1f5f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1f600 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1f610 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1f620 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1f630 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1f640 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1f650 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1f660 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1f670 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1f680 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1f690 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1f6a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1f6b0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1f6c0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1f6d0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1f6e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1f6f0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1f700 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1f710 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1f720 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1f730 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1f740 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1f750 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1f760 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1f770 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1f780 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f790 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1f7a0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1f7b0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1f7c0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1f7d0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1f7e0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1f7f0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1f800 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1f810 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1f820 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1f830 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1f840 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1f850 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1f860 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1f870 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1f880 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1f890 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1f8a0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1f8b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1f8c0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1f8d0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1f8e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1f8f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f900 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f910 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1f920 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1f930 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1f940 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1f950 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1f960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1f970 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f980 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1f990 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1f9a0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1f9b0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1f9c0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1f9d0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1f9e0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1f9f0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1fa00 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1fa10 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1fa20 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1fa30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1fa40 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1fa50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1fa60 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1fa70 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1fa80 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1fa90 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1faa0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1fab0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1fac0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1fad0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1fae0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1faf0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1fb00 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1fb10 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1fb20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1fb30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1fb40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1fb50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1fb60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1fb70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1fb80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1fb90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1fba0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1fbb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1fbc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1fbd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1fbe0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1fbf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1fc00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fc10 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1fc20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1fc30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1fc40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1fc50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1fc60 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1fc70 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1fc80 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1fc90 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1fca0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1fcb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fcc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1fcd0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1fce0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1fcf0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1fd00 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1fd10 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1fd20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1fd30 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1fd40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1fd50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fd60 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1fd70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fd80 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1fd90 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1fda0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1fdb0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1fdc0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1fdd0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1fde0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1fdf0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1fe00 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1fe10 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1fe20 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1fe30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1fe40 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1fe50 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1fe60 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1fe70 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1fe80 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1fe90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fea0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1feb0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1fec0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1fed0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fee0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1fef0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1ff00 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1ff10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ff20 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1ff30 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1ff40 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1ff50 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1ff60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1ff70 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1ff80 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1ff90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ffa0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1ffb0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1ffc0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1ffd0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1ffe0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1fff0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
20000 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
20010 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
20020 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
20030 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
20040 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
20050 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
20060 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
20070 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
20080 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
20090 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
200a0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
200b0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
200c0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
200d0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
200e0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
200f0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
20100 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
20110 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
20120 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
20130 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
20140 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
20150 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
20160 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
20170 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
20180 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
20190 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
201a0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
201b0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
201c0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
201d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
201e0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
201f0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
20200 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
20210 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
20220 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
20230 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
20240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
20250 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
20260 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
20270 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
20280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
20290 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
202a0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
202b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
202c0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
202d0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
202e0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
202f0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
20300 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
20310 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
20320 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
20330 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
20340 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
20350 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
20360 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
20370 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
20380 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
20390 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
203a0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
203b0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
203c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
203d0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
203e0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
203f0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
20400 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45  D: sqlite3.** KE
20410 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69  YWORDS: {authori
20420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a  zer callback}.**
20430 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
20440 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
20450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20460 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
20470 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
20480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
20490 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
204a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
204b0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
204c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
204d0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
204e0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
204f0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
20500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20510 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
20520 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
20530 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
20540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20550 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
20560 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b  _prepare16()], [
20570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20580 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  6_v2()],.** and 
20590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
205a0 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76  16_v3()].  ^At v
205b0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
205c0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
205d0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
205e0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
205f0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
20600 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
20610 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
20620 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20630 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
20640 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
20650 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
20660 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
20670 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
20680 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
20690 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
206a0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
206b0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
206c0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
206d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
206e0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
206f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20700 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
20710 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
20720 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
20730 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
20740 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
20750 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
20760 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
20770 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
20780 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20790 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
207a0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
207b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
207c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
207d0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
207e0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
207f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20800 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
20810 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
20820 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
20830 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
20840 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
20850 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
20860 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
20870 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
20880 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
20890 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
208a0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
208b0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
208c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
208d0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
208e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
208f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
20900 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
20910 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
20920 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
20930 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
20940 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
20950 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
20960 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
20970 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
20980 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
20990 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
209a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
209b0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
209c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
209d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
209e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
209f0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
20a00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
20a10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
20a20 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
20a30 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
20a40 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
20a50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
20a60 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
20a70 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
20a80 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
20a90 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
20aa0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
20ab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
20ac0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69   either NULL poi
20ad0 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65  nters or zero-te
20ae0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
20af0 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  .** that contain
20b00 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
20b10 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
20b20 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
20b30 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63  rized..** Applic
20b40 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61  ations must alwa
20b50 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74  ys be prepared t
20b60 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55  o encounter a NU
20b70 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e  LL pointer in an
20b80 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72  y.** of the thir
20b90 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69  d through the si
20ba0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f  xth parameters o
20bb0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  f the authorizat
20bc0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
20bd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20be0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20bf0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
20c00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20c10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
20c20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
20c30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20c40 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
20c50 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
20c60 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
20c70 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
20c80 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
20c90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
20ca0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
20cb0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
20cc0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
20cd0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
20ce0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
20cf0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
20d00 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
20d10 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
20d20 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
20d30 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
20d40 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68   a table..** ^Wh
20d50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65  en a table is re
20d60 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53  ferenced by a [S
20d70 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f  ELECT] but no co
20d80 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a  lumn values are.
20d90 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  ** extracted fro
20da0 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f  m that table (fo
20db0 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71  r example in a q
20dc0 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45  uery like.** "SE
20dd0 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52  LECT count(*) FR
20de0 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68  OM tab") then th
20df0 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  e [SQLITE_READ] 
20e00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20e10 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ack.** is invoke
20e20 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20  d once for that 
20e30 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c  table with a col
20e40 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73  umn name that is
20e50 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
20e60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
20e70 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20e80 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20ea0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20eb0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20ec0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20ed0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20ee0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20ef0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20f00 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20f10 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
20f20 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
20f30 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
20f40 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
20f50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20f60 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
20f70 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
20f80 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
20f90 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
20fa0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20fc0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
20fd0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
20fe0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
20ff0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
21000 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
21010 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
21020 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
21030 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
21040 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
21050 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
21060 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
21070 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
21080 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
21090 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
210a0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
210b0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
210c0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
210d0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
210e0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
210f0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
21100 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
21110 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
21120 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
21130 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
21140 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
21150 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
21160 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
21170 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
21180 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21190 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
211a0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
211b0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
211c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
211d0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
211e0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
211f0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21200 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21210 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
21220 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
21230 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
21240 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
21250 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
21260 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
21270 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
21280 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
21290 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
212a0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
212b0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
212c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
212d0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
212e0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
212f0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21310 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
21320 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
21330 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21340 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
21350 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
21360 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
21370 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21380 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21390 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
213a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
213b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
213c0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
213d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
213e0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
213f0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21400 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21420 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21430 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21440 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
21450 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
21460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21470 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21480 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21490 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
214a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
214b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
214c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
214d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
214e0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
214f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21500 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
21510 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
21520 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
21530 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
21540 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
21550 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
21560 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21570 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21590 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
215a0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
215b0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
215c0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
215d0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
215e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
215f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21600 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21610 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21620 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
21630 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21640 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
21650 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
21660 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21670 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21680 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21690 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
216a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
216b0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
216c0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
216d0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
216e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
216f0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
21710 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
21720 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
21730 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
21740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
21750 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
21760 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
21770 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
21780 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
21790 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
217a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
217b0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
217c0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
217d0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
217e0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
217f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21800 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21810 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
21820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21830 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
21840 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
21850 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
21860 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
21870 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
21880 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
21890 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
218a0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
218b0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
218c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
218d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
218e0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
218f0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
21900 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21910 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
21920 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
21930 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
21940 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
21950 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
21960 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
21970 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
21980 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
21990 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
219a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
219b0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
219c0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
219d0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
219e0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
219f0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
21a00 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
21a10 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
21a20 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
21a30 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
21a40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21a50 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
21a60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21a70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21a80 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
21a90 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
21aa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
21ab0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
21ac0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
21ad0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
21ae0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
21af0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
21b00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
21b10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21b20 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
21b30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
21b40 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
21b50 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
21b60 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
21b70 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
21b80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
21b90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21ba0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
21bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
21bc0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
21bd0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
21be0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
21bf0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
21c00 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
21c10 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
21c20 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
21c30 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
21c40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
21c50 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
21c60 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
21c70 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
21c80 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
21c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
21ca0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
21cb0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
21cc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
21cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21ce0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21cf0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
21d00 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
21d10 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
21d20 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
21d30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21d40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21d50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
21d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
21d70 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
21d80 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
21d90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
21da0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
21db0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
21dc0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
21dd0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
21de0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
21df0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
21e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
21e40 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
21e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21e60 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
21e70 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
21e80 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21e90 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21eb0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
21ec0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
21ed0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21ee0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21f00 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
21f10 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
21f20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21f30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21f40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21f50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21f60 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
21f70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21f80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21f90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21fa0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
21fb0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21fc0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21fd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21fe0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21ff0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
22000 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22010 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22030 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
22040 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
22050 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22060 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22080 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
22090 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
220a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
220b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
220c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
220d0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
220e0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
220f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22100 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22120 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
22130 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
22140 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22150 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22170 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
22180 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
22190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
221a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
221b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
221c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
221d0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
221e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
221f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22210 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
22220 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
22230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22240 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22260 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
22270 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
22280 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22290 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
222a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
222b0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
222c0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
222d0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
222e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
222f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22300 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
22310 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
22320 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22330 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22350 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
22360 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
22370 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22380 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22390 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
223a0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
223b0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
223c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
223d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
223e0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
223f0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
22400 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
22410 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
22420 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
22430 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
22440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22450 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
22460 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
22470 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22480 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
22490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
224a0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
224b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
224c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
224d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
224e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
224f0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
22500 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22520 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
22530 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
22540 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22550 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22570 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
22580 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
22590 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
225a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
225b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
225c0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
225d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
225e0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
225f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22610 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
22620 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
22630 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22640 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22660 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
22670 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
22680 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
226a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
226b0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
226c0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
226d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
226e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
226f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22700 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
22710 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
22720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
22730 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
22740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22750 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
22760 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
22770 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22780 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
227a0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
227b0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
227c0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
227d0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
227e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
227f0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
22800 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
22810 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
22820 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
22830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
22840 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
22850 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
22860 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
22870 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
22880 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
22890 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
228a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
228b0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
228c0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
228d0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
228e0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
228f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22900 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
22910 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
22920 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
22930 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22940 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
22950 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
22960 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
22970 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
22980 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
22990 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
229a0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
229b0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
229c0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
229d0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
229e0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
229f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
22a00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22a10 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22a20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
22a40 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
22a50 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
22a60 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
22a70 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
22a80 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
22a90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22aa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22ab0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
22ac0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
22ad0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
22ae0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
22af0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
22b00 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
22b10 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
22b20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22b30 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
22b40 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
22b50 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
22b60 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
22b70 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
22b80 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
22b90 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
22ba0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
22bb0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
22bc0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
22bd0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
22be0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
22bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22c00 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
22c10 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
22c20 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
22c30 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
22c40 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
22c50 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
22c60 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
22c70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22c80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22c90 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
22ca0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
22cb0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
22cc0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
22cd0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
22ce0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
22cf0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
22d00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
22d10 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
22d20 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
22d30 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
22d40 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
22d50 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
22d60 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
22d80 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
22d90 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
22da0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
22db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
22dc0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
22dd0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
22de0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
22df0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
22e00 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
22e10 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
22e20 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
22e30 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22e40 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
22e50 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
22e60 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
22e70 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
22e80 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
22e90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22ea0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22eb0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
22ec0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
22ed0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22ee0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
22ef0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
22f00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
22f10 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22f20 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
22f30 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72  3*,.   void(*xTr
22f40 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
22f50 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
22f60 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22f70 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22f80 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
22f90 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
22fa0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
22fb0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
22fc0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
22fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22fe0 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
22ff0 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
23000 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
23010 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
23020 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
23030 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
23040 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
23050 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
23060 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
23070 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
23080 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74  ng logic.  The t
23090 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
230a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
230b0 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f  ce_v2()] is an O
230c0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
230d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
230e0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
230f0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
23100 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
23110 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
23120 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
23130 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23140 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
23150 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
23160 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
23170 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
23180 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
23190 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
231a0 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
231b0 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
231c0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
231d0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
231e0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
231f0 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
23200 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
23210 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
23220 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23230 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
23240 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
23250 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
23260 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23270 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
23280 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
23290 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
232a0 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
232b0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
232c0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
232d0 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
232e0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
232f0 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
23300 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
23310 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
23320 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
23330 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
23340 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
23350 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
23360 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
23370 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
23380 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
23390 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
233a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
233b0 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
233c0 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
233d0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
233e0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
233f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23400 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23410 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
23420 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
23430 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
23440 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
23450 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
23460 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
23470 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23480 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
23490 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
234a0 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
234b0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
234c0 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
234d0 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
234e0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
234f0 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
23500 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
23510 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
23520 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
23530 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
23540 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
23550 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
23560 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
23570 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
23580 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
23590 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
235a0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
235b0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
235c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
235d0 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
235e0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
235f0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
23600 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
23610 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
23620 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
23630 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
23640 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
23650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23660 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
23670 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23680 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23690 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
236a0 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
236b0 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
236c0 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
236d0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
236e0 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
236f0 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
23700 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
23710 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
23720 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
23730 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
23740 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23750 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
23760 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
23770 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
23780 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
23790 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
237a0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
237b0 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
237c0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
237d0 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
237e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
237f0 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
23800 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
23810 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
23820 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
23830 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23840 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23850 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
23860 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
23870 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
23880 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
23890 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
238a0 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
238b0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
238c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
238d0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
238e0 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
238f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
23900 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
23910 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
23920 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23930 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23940 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
23950 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
23960 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
23970 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
23980 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
23990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
239a0 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
239b0 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
239c0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
239d0 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
239e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
239f0 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
23a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23a10 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
23a20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
23a30 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
23a40 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
23a50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
23a60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23a70 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
23a80 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
23a90 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
23aa0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
23ab0 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
23ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
23ad0 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
23ae0 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
23af0 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
23b00 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
23b10 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
23b20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
23b30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
23b40 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
23b50 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
23b60 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
23b70 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
23b80 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
23b90 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
23ba0 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
23bb0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
23bc0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
23bd0 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
23be0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
23bf0 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
23c00 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
23c10 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
23c20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
23c30 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
23c40 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
23c50 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
23c60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23c70 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
23c80 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
23c90 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
23ca0 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
23cb0 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
23cc0 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
23cd0 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
23ce0 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
23cf0 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
23d00 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
23d10 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
23d20 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
23d30 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
23d40 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
23d50 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
23d60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
23d70 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
23d80 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
23d90 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
23da0 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
23db0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23dc0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
23dd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
23de0 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
23df0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
23e00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
23e10 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
23e20 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23e40 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
23e50 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
23e60 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
23e70 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23e80 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23e90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23ea0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
23eb0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
23ec0 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
23ed0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
23ee0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
23ef0 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
23f00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23f10 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
23f20 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
23f30 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
23f40 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
23f50 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
23f60 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
23f70 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
23f80 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
23f90 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
23fa0 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
23fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
23fc0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
23fd0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
23fe0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23ff0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
24000 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
24010 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
24020 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
24030 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
24040 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
24050 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
24060 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
24070 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
24080 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
24090 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
240a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
240b0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
240c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
240d0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
240e0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
240f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
24100 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
24110 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
24120 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
24130 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
24140 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
24150 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
24160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24170 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
24180 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
24190 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
241a0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
241b0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
241c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
241d0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
241e0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
241f0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
24200 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
24210 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
24220 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
24230 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
24240 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
24250 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
24260 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
24270 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
24280 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
24290 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
242a0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
242b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
242c0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
242d0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
242e0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
242f0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
24300 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
24310 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
24320 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
24330 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
24340 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24350 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
24360 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
24370 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
24380 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
24390 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
243a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
243b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
243c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
243d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
243e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
243f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
24400 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
24410 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
24420 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
24430 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
24440 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24450 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
24460 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24470 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24480 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
244a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
244b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
244c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
244d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
244e0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
244f0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
24500 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
24510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24520 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
24530 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
24540 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
24550 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
24560 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24570 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
24580 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
24590 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
245a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
245b0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
245c0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
245d0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
245e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
245f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
24600 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
24610 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
24620 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
24630 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
24640 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
24650 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
24660 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
24670 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
24680 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
246a0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
246b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
246c0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
246d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
246e0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
246f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24700 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
24710 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
24720 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
24730 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
24740 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
24750 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
24760 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
24770 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24780 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
24790 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
247a0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
247b0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
247c0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
247d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
247e0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
247f0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
24800 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24810 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
24820 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
24830 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
24840 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
24850 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
24860 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
24870 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
24880 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
24890 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
248a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
248b0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
248c0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
248d0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
248e0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
248f0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
24900 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
24910 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
24920 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
24930 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
24940 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
24950 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
24960 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
24970 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
24980 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
24990 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
249a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
249b0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
249c0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
249d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
249e0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
249f0 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
24a00 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
24a10 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
24a20 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
24a30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
24a40 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
24a50 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
24a60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
24a70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24a80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24a90 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
24aa0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
24ab0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
24ac0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
24ad0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
24ae0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
24af0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
24b00 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
24b10 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
24b20 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
24b30 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
24b40 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
24b50 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
24b60 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
24b70 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
24b80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
24b90 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
24ba0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24bb0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
24bc0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
24bd0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
24be0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
24bf0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
24c00 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24c10 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
24c20 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
24c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
24c40 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
24c50 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24c60 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
24c70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24c80 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
24c90 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24ca0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
24cb0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24cc0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
24cd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24ce0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24cf0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
24d00 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
24d10 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
24d20 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
24d30 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
24d40 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
24d50 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
24d60 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24d70 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24d80 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24d90 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24da0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
24db0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
24dc0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
24dd0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
24de0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
24df0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
24e00 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
24e10 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
24e20 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
24e30 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
24e40 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
24e50 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24e60 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24e70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24e80 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
24e90 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
24ea0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24eb0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24ec0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24ed0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
24ee0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
24ef0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
24f00 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
24f10 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
24f20 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
24f30 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
24f40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
24f50 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
24f60 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
24f70 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
24f80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24f90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24fa0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
24fb0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
24fc0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
24fd0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24fe0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
24ff0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
25000 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
25010 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
25020 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
25030 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
25040 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
25050 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
25060 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
25070 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25080 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
25090 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
250a0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
250b0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
250c0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
250d0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
250e0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
250f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
25100 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
25110 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
25120 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
25130 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
25140 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
25150 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
25160 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
25170 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25180 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
25190 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
251a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
251b0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
251c0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
251d0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
251e0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
251f0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
25200 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25210 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
25220 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
25230 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
25240 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
25250 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
25260 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
25270 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
25280 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25290 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
252a0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
252b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
252c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
252d0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
252e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
252f0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
25300 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
25310 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
25320 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
25330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
25340 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25350 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25360 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
25370 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
25380 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
25390 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
253a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
253b0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
253c0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
253d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
253e0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
253f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25400 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
25410 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
25420 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
25430 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
25440 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
25450 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25460 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
25470 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25480 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
25490 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
254a0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
254b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
254c0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
254d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
254e0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
254f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25500 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
25510 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
25520 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
25530 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
25540 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
25550 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
25560 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
25570 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
25580 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
25590 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
255a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
255b0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
255c0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
255d0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
255e0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
255f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
25600 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
25610 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
25620 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
25630 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25640 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
25650 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
25660 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25670 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
25680 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
25690 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
256a0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
256b0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
256c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
256d0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
256e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
256f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25700 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
25710 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
25720 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
25730 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
25740 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
25750 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
25760 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
25770 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
25780 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25790 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
257a0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
257b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
257c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
257d0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
257e0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
257f0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
25800 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
25810 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
25820 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
25830 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
25840 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25850 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
25860 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
25870 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
25880 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
25890 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
258a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
258b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
258c0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
258d0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
258e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
258f0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
25900 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
25910 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
25920 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
25930 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
25940 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
25950 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
25960 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25970 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
25980 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
25990 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
259a0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
259b0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
259c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
259d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
259e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
259f0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
25a00 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
25a10 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
25a20 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
25a30 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
25a40 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
25a50 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
25a60 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
25a70 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
25a80 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
25a90 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
25aa0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
25ab0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
25ac0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
25ad0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
25ae0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
25af0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
25b00 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
25b10 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
25b20 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
25b30 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
25b40 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
25b50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
25b60 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
25b70 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
25b80 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
25b90 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
25ba0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
25bb0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
25bc0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25bd0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
25be0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
25bf0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
25c00 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
25c10 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
25c20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
25c30 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
25c40 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
25c50 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
25c60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
25c70 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
25c80 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
25c90 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
25ca0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
25cb0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
25cc0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
25cd0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
25ce0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
25cf0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
25d00 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
25d10 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25d20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
25d30 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
25d40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
25d50 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
25d60 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
25d70 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
25d80 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
25d90 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
25da0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
25db0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
25dc0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
25dd0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
25de0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
25df0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
25e00 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
25e10 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
25e20 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
25e30 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
25e40 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
25e50 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
25e60 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
25e70 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
25e80 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25e90 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25ea0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25eb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25ec0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25ed0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25ee0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25ef0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25f00 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25f10 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
25f20 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
25f30 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
25f40 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
25f50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
25f60 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
25f70 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25f80 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25f90 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25fa0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25fb0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25fc0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25fd0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25fe0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25ff0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26000 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26010 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
26020 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
26030 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26040 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
26050 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
26060 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
26070 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
26080 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
26090 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
260a0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
260b0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
260c0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
260d0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
260e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
260f0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
26100 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
26110 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
26120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
26130 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
26140 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
26150 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
26160 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
26170 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
26180 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
26190 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
261a0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
261b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
261c0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
261d0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
261e0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
261f0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
26200 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
26210 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
26220 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
26230 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
26240 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
26250 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
26260 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
26270 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
26280 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
26290 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
262a0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
262b0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
262c0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
262d0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
262e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
262f0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
26300 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
26310 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
26320 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
26330 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
26340 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
26350 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
26360 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
26370 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
26380 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
26390 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
263a0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
263b0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
263c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
263d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
263e0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
263f0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
26400 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
26410 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
26420 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
26430 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
26440 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
26450 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
26460 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26470 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
26480 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26490 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
264a0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
264b0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
264c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
264d0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
264e0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
264f0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
26500 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
26510 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
26520 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
26530 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
26540 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
26550 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
26560 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
26570 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
26580 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
26590 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
265a0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
265b0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
265c0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
265d0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
265e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
265f0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
26600 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26610 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
26620 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
26630 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
26640 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
26650 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
26660 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
26670 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
26680 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
26690 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
266a0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
266b0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
266c0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
266d0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
266e0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
266f0 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
26700 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
26710 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
26720 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
26730 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
26740 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
26750 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
26760 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
26770 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
26780 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
26790 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
267a0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
267b0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
267c0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
267d0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
267e0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
267f0 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
26800 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
26810 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
26820 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
26830 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
26840 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
26850 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
26860 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
26870 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
26880 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
26890 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
268a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
268b0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
268c0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
268d0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
268e0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
268f0 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
26900 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
26910 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
26920 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
26930 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
26940 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
26950 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
26960 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
26970 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
26980 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
26990 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
269a0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
269b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
269c0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
269d0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
269e0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
269f0 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
26a00 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
26a10 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
26a20 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
26a30 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
26a40 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
26a50 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
26a60 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
26a70 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
26a80 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
26a90 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
26aa0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
26ab0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
26ac0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
26ad0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
26ae0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
26af0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
26b00 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
26b10 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
26b20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26b30 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
26b40 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
26b50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26b60 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
26b70 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
26b80 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
26b90 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
26ba0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
26bb0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
26bc0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
26bd0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
26be0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
26bf0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
26c00 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
26c10 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
26c20 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
26c30 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
26c40 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
26c50 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
26c60 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
26c70 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
26c80 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
26c90 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
26ca0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26cb0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26cc0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26cd0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26ce0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26cf0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26d00 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
26d10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
26d20 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26d30 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
26d40 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
26d50 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
26d60 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
26d70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26d80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26d90 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26da0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
26db0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
26dc0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
26dd0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26de0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26df0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
26e00 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
26e10 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
26e20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
26e30 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
26e40 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
26e50 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
26e60 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
26e70 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
26e80 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
26e90 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
26ea0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
26eb0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
26ec0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
26ed0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
26ee0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26ef0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26f00 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26f10 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
26f20 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
26f30 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
26f40 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
26f50 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
26f60 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
26f70 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
26f80 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26f90 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26fa0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
26fb0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26fc0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
26fd0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26fe0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26ff0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
27000 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
27010 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
27020 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27030 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
27040 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
27050 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
27060 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
27070 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
27080 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
27090 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
270a0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
270b0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
270c0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
270d0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
270e0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
270f0 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
27100 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
27110 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
27120 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
27130 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
27140 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
27150 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
27160 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
27170 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
27180 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
27190 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
271a0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
271b0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
271c0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
271d0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
271e0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
271f0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
27200 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
27210 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
27220 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
27230 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
27240 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27250 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
27260 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
27270 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
27280 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
27290 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
272a0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
272b0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
272c0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
272d0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
272e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
272f0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
27300 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
27310 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
27320 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
27330 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
27340 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27350 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
27360 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
27370 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
27380 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
27390 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
273a0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
273b0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
273c0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
273d0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
273e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
273f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
27400 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
27410 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
27420 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
27430 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
27440 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
27450 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
27460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
27470 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
27480 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
27490 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
274a0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
274b0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
274c0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
274d0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
274e0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
274f0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
27500 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
27510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
27520 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
27530 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
27540 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
27550 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
27560 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
27570 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
27580 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
27590 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
275a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
275b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
275c0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
275d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
275e0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
275f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
27600 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
27610 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
27620 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27630 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
27640 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
27650 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
27660 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27670 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27680 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27690 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
276a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
276b0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
276c0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
276d0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
276e0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
276f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
27700 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
27710 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
27720 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
27730 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27740 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27750 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27760 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
27770 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27780 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27790 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
277a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
277b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
277c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
277d0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
277e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
277f0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
27800 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
27810 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
27820 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
27830 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
27840 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
27850 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
27860 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
27870 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
27880 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
27890 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
278a0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
278b0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
278c0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
278d0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
278e0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
278f0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
27900 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
27910 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
27920 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
27930 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
27940 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
27950 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27960 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
27970 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27980 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
27990 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
279a0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
279b0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
279c0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
279d0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
279e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
279f0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
27a00 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
27a10 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
27a20 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
27a30 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
27a40 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
27a50 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27a60 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
27a70 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27a80 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
27a90 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27aa0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27ab0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27ac0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
27ad0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27ae0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
27af0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27b00 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
27b10 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
27b20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27b30 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27b40 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
27b50 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
27b60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
27b70 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27b80 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27b90 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27ba0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27bb0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27bc0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
27bd0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
27be0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
27bf0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
27c00 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
27c10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27c20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27c30 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
27c40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
27c50 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27c60 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
27c70 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27c80 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27c90 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27ca0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27cb0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27cc0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27cd0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27ce0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
27cf0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
27d00 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
27d10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27d20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
27d30 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
27d40 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
27d50 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
27d60 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27d70 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27d80 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27d90 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27da0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27db0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27dc0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27dd0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
27de0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27df0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27e00 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
27e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27e20 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
27e30 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
27e40 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
27e50 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
27e60 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27e70 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27e80 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27e90 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27ea0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27eb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27ec0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27ed0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27ee0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27ef0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27f00 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
27f10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
27f20 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27f30 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27f40 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
27f50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27f60 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27f70 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27f80 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27f90 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27fa0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27fb0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27fc0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27fd0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27fe0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27ff0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28000 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
28010 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
28020 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
28030 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
28040 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28050 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28060 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
28070 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
28080 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
28090 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
280a0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
280b0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
280c0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
280d0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
280e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
280f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
28100 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
28110 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
28120 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
28130 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
28140 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
28150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
28160 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
28170 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
28180 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
28190 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
281a0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
281b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
281c0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
281d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
281e0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
281f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
28200 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
28210 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
28220 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
28230 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
28240 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
28250 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
28260 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
28270 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
28280 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
28290 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
282a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
282b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
282c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
282d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
282e0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
282f0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
28300 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
28310 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
28320 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
28330 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
28340 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
28350 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
28360 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
28370 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
28380 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
28390 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
283a0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
283b0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
283c0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
283d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
283e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
283f0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
28400 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28410 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
28420 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
28430 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
28440 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
28450 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
28460 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
28470 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
28480 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
28490 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
284a0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
284b0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
284c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
284d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
284e0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
284f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
28500 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
28510 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28520 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
28530 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
28540 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
28550 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
28560 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
28570 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
28580 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28590 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
285a0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
285b0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
285c0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
285d0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
285e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
285f0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
28600 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
28610 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
28620 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
28630 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
28640 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
28650 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
28660 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
28670 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
28680 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
28690 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
286a0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
286b0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
286c0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
286d0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
286e0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
286f0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
28700 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
28710 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
28720 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
28730 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
28740 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
28750 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
28760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28770 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
28780 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
28790 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
287a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
287b0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
287c0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
287d0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
287e0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
287f0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
28800 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
28810 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
28820 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
28830 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
28840 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
28850 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
28860 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
28870 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
28880 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
28890 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
288a0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
288b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
288c0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
288d0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
288e0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
288f0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
28900 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
28910 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
28920 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
28930 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28940 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
28950 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
28960 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
28970 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
28980 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
28990 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
289a0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
289b0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
289c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
289d0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
289e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
289f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28a10 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28a20 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28a30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28a40 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28a50 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28a60 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
28a70 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
28a80 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
28a90 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
28aa0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
28ab0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
28ac0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28ad0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28ae0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28af0 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28b00 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28b10 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
28b20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
28b30 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
28b40 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
28b50 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
28b60 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
28b70 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28b80 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28b90 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28ba0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28bb0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28bc0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28bd0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28be0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28bf0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28c00 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28c10 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28c20 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28c30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28c40 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
28c50 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
28c60 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
28c70 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28c80 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28c90 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28ca0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28cb0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28cd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28ce0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28cf0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28d00 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28d10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28d20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
28d30 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
28d40 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
28d50 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28d60 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
28d70 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28d80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28d90 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28da0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28db0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28dc0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28dd0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28de0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28df0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28e00 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28e10 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
28e20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
28e30 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28e40 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
28e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
28e60 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
28e70 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28e80 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28e90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28ea0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28eb0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28ec0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28ed0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28ee0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28ef0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28f00 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28f10 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28f20 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28f30 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28f40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28f50 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28f60 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28f70 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28f80 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28f90 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28fa0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28fb0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28fc0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28fd0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28fe0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28ff0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
29000 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
29010 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
29020 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
29030 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
29040 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
29050 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
29060 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
29070 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
29080 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
29090 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
290a0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
290b0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
290c0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
290d0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
290e0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
290f0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
29100 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
29110 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
29120 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
29130 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29140 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
29150 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
29160 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
29170 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
29180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29190 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
291a0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
291b0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
291c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
291d0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
291e0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
291f0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
29200 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
29210 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
29220 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
29230 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
29240 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
29250 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
29260 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
29270 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
29280 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
29290 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
292a0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
292b0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
292c0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
292d0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
292e0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
292f0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
29300 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
29310 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
29320 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
29330 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
29340 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
29350 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
29360 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
29370 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
29380 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
29390 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
293a0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
293b0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
293c0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
293d0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
293e0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
293f0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
29400 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
29410 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
29420 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
29430 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
29440 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
29450 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
29460 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
29470 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
29480 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
29490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
294a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
294b0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
294c0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
294d0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
294e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
294f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
29500 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
29510 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
29520 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
29530 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
29540 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
29550 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
29560 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
29570 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
29580 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
29590 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
295a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
295b0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
295c0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
295d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
295e0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
295f0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
29600 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
29610 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
29620 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
29630 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
29640 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
29650 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
29660 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
29670 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
29680 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
29690 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
296a0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
296b0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
296c0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
296d0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
296e0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
296f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
29700 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
29710 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
29720 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
29730 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
29740 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
29750 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29760 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
29770 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29780 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
29790 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
297a0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
297b0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
297c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
297d0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
297e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
297f0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
29800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29810 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
29820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
29830 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
29840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29850 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
29860 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29870 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
29880 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29890 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
298a0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
298b0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
298c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
298d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
298e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
298f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29900 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
29910 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
29920 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
29930 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
29940 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29950 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
29960 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29970 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
29980 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29990 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
299a0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
299b0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
299c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
299d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
299e0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
299f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
29a00 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
29a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29a20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29a30 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
29a40 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
29a50 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
29a60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29a70 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
29a80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29a90 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
29aa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29ab0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
29ac0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
29ad0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
29ae0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
29af0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
29b00 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
29b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29b20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
29b30 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
29b40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
29b50 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
29b60 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
29b70 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
29b80 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29b90 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
29ba0 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
29bb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
29bc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29bd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29be0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
29bf0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
29c00 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
29c10 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
29c20 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
29c30 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
29c40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
29c60 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
29c70 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29c80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
29c90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29ca0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
29cb0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
29cc0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
29cd0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
29ce0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29cf0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
29d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
29d10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
29d20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29d30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
29d40 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
29d50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
29d60 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
29d70 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
29d80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29d90 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29da0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
29db0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29dc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
29dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29de0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
29df0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
29e00 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
29e10 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
29e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29e30 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29e40 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29e50 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29e60 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
29e70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
29e80 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
29e90 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
29ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29eb0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29ec0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
29ed0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
29ee0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
29ef0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29f00 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
29f10 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
29f20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
29f30 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
29f40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
29f50 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
29f60 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
29f70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29f80 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29f90 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
29fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29fb0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
29fc0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
29fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29fe0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
29ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2a000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a010 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2a020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2a030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a040 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2a050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2a060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a070 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a090 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2a0a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a0b0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2a0c0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2a0d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a0f0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2a100 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2a110 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2a120 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2a130 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a140 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2a150 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2a160 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2a170 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2a180 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2a190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2a1a0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2a1b0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2a1c0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2a1d0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2a1e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2a1f0 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2a200 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2a210 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2a220 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2a230 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2a240 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2a250 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2a260 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2a270 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2a280 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2a290 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2a2a0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2a2b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2a2c0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2a2d0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2a2e0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2a2f0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2a300 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2a310 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2a320 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2a330 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2a340 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2a350 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2a360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a370 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2a380 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2a390 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2a3a0 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2a3b0 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2a3c0 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2a3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2a3e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2a3f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2a400 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2a410 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a420 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2a430 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2a440 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2a450 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2a460 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2a470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2a480 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2a490 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2a4a0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2a4b0 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2a4c0 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2a4d0 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2a4e0 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2a4f0 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2a500 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2a510 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2a520 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2a530 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2a540 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2a550 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2a560 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2a570 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2a580 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2a590 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20  ARE_PERSISTENT  
2a5a0 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31              0x01
2a5b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a5c0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2a5d0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2a5e0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2a5f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2a600 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2a610 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2a620 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2a630 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2a640 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2a650 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2a660 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2a670 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2a680 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2a690 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2a6a0 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2a6b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2a6c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2a6d0 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2a6e0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2a6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2a700 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2a710 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2a720 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2a730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a740 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2a750 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2a760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2a770 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2a780 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2a790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a7a0 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2a7b0 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2a7c0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2a7d0 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2a7e0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2a7f0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2a800 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2a810 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2a820 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2a830 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2a840 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2a850 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2a860 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2a870 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2a880 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2a890 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2a8a0 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2a8b0 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2a8c0 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2a8d0 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2a8e0 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2a8f0 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2a900 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2a910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2a920 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2a930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a940 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2a950 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2a960 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2a970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2a980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a990 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2a9a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2a9b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a9c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2a9d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2a9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2a9f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2aa00 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2aa10 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2aa20 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2aa30 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2aa40 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2aa50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2aa60 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2aa70 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2aa80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2aa90 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2aaa0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2aab0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2aac0 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2aad0 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2aae0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2aaf0 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2ab00 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2ab10 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2ab20 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2ab30 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2ab40 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2ab50 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2ab60 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2ab70 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2ab80 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2ab90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2aba0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2abb0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2abc0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2abd0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2abe0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2abf0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2ac00 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2ac10 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2ac20 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2ac30 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2ac40 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2ac50 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2ac60 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2ac70 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2ac80 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2ac90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aca0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2acb0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2acc0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2acd0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2ace0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2acf0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2ad00 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2ad10 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2ad20 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2ad30 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2ad40 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2ad50 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2ad60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2ad70 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2ad80 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2ad90 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2ada0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2adb0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2adc0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2add0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2ade0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2adf0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2ae00 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2ae10 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2ae20 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2ae30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ae40 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2ae50 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2ae60 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2ae70 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2ae80 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2ae90 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2aea0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2aeb0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2aec0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2aed0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2aee0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2aef0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2af00 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2af10 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2af20 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2af30 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2af40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2af50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2af60 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2af70 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2af80 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2af90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2afa0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2afb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2afc0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2afd0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2afe0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2aff0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2b000 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2b010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b020 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2b030 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b040 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2b050 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2b060 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2b070 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2b080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2b090 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2b0a0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2b0b0 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2b0c0 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2b0d0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2b0e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b0f0 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2b100 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2b110 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2b120 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2b130 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2b140 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2b150 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2b160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2b170 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2b180 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2b190 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2b1a0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2b1b0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2b1c0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2b1d0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2b1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2b1f0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2b200 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2b210 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2b220 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2b230 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2b240 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2b250 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2b260 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2b270 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2b280 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2b290 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2b2a0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2b2b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2b2c0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2b2d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2b2e0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2b2f0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2b300 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2b310 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2b320 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2b330 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2b340 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2b350 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2b360 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2b370 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2b380 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2b390 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2b3a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2b3b0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2b3c0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2b3d0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2b3e0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2b3f0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2b400 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2b410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b420 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2b430 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2b440 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2b450 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2b460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b470 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2b480 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2b490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2b4a0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2b4b0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2b4c0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2b4d0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2b4e0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2b4f0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2b500 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2b510 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2b520 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2b530 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2b540 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2b550 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2b560 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2b570 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2b580 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2b590 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2b5a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2b5b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2b5c0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2b5d0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2b5e0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2b5f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2b600 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2b610 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2b620 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2b630 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2b640 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2b650 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2b660 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2b670 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2b680 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2b690 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2b6a0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2b6b0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2b6c0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2b6d0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2b6e0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2b6f0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2b700 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2b710 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2b720 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2b730 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2b740 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2b750 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2b760 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2b770 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2b780 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2b790 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2b7a0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2b7b0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2b7c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b7d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2b7e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2b7f0 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2b800 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2b810 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2b820 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2b830 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2b840 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2b850 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2b860 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2b870 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2b880 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2b890 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2b8a0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2b8b0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2b8c0 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2b8d0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2b8e0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2b8f0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2b900 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2b910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b920 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2b930 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2b940 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  er..** </ol>.*/.
2b950 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b960 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2b970 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2b980 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2b990 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2b9a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2b9b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2b9c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2b9d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2b9e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2b9f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ba00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2ba10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2ba20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2ba30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2ba40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ba50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2ba60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2ba70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2ba80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ba90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2baa0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2bab0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2bac0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bad0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bae0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2baf0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2bb00 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2bb10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2bb20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2bb30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2bb40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2bb50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2bb60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2bb70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2bb80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2bb90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2bba0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2bbb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2bbc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2bbd0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2bbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2bbf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2bc00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2bc10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2bc20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2bc30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2bc40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2bc50 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2bc60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2bc70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2bc80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2bc90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2bca0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2bcb0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2bcc0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2bcd0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2bce0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2bcf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2bd00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2bd10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2bd20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2bd30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2bd40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2bd50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2bd60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2bd70 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  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 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *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 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2bde0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2bdf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2be00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2be10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2be20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2be30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2be40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2be50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2be60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2be70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2be80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2be90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2bea0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2beb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2bec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2bed0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2bee0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2bef0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2bf00 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2bf10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2bf20 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2bf30 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2bf40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2bf50 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2bf60 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2bf70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2bf80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2bf90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2bfa0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2bfb0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2bfc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2bfd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2bfe0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2bff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c000 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c  pare16_v3(.  sql
2c010 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c020 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c030 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c040 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2c050 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c060 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2c070 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c080 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c090 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c0a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c0b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2c0c0 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2c0d0 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2c0e0 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2c0f0 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c110 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c120 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c130 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c140 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c150 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c160 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c170 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2c180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2c190 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2c1a0 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2c1b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c1d0 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2c1e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c1f0 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2c200 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2c210 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2c220 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2c230 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2c240 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2c250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
2c260 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2c270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c280 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2c2a0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
2c2b0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
2c2c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2c2d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2c2e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c2f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2c300 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2c310 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2c320 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2c330 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2c340 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2c350 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2c360 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2c370 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2c380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c390 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2c3a0 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2c3b0 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2c3c0 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2c3d0 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2c3e0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2c3f0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2c400 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2c410 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2c420 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2c430 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2c440 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2c450 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2c460 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2c470 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2c480 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2c490 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2c4a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c4b0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2c4c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2c4d0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2c4e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2c4f0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2c500 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2c510 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2c520 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2c530 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2c540 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2c550 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2c560 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2c570 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2c580 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2c590 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2c5a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c5b0 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2c5c0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2c5d0 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2c5e0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2c5f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2c600 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2c610 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2c620 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2c630 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2c640 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2c650 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2c660 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2c670 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2c680 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2c690 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2c6a0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2c6b0 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2c6c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2c6d0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2c6e0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2c6f0 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2c700 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2c710 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2c720 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2c730 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c740 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2c750 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2c760 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2c770 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2c780 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2c790 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c7a0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2c7b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c7c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2c7d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2c7e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c7f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c800 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2c810 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c820 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2c830 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2c840 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c860 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2c870 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c880 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2c890 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2c8a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2c8b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2c8c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2c8d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2c8e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2c8f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2c900 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2c910 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c920 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c930 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2c940 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2c950 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2c960 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2c970 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2c980 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2c990 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2c9a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2c9b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2c9c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2c9d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2c9e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2ca00 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2ca10 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2ca20 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2ca30 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2ca40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ca50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2ca60 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2ca70 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2ca80 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2ca90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2caa0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2cab0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cac0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2cad0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2cae0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2caf0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2cb00 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2cb10 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2cb20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2cb30 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2cb40 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2cb50 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2cb60 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2cb70 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2cb80 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2cb90 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2cba0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2cbb0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2cbc0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2cbd0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2cbe0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2cbf0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2cc00 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2cc10 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2cc20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2cc30 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2cc40 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2cc50 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2cc60 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2cc70 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2cc80 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2cc90 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2cca0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2ccb0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2ccc0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2ccd0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2cce0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2ccf0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2cd10 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2cd20 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2cd30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2cd40 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2cd50 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2cd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2cd70 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2cd80 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2cd90 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2cda0 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2cdb0 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2cdc0 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2cdd0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2cde0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2cdf0 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2ce00 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2ce10 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2ce20 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2ce30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2ce40 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2ce50 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2ce60 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  commands..*/.int
2ce70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ce80 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2ce90 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2cea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2ceb0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2cec0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ced0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2cee0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2cef0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2cf00 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2cf10 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2cf20 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2cf30 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2cf40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2cf50 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2cf60 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2cf70 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2cf80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2cf90 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2cfa0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2cfb0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2cfc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2cfd0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2cfe0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2cff0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2d000 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d010 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2d020 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2d030 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2d040 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2d050 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d060 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2d070 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2d080 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2d090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2d0a0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2d0b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2d0c0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2d0d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2d0e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2d0f0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2d100 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2d110 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2d120 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2d130 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2d140 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2d150 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2d160 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2d170 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2d180 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2d190 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2d1a0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2d1b0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2d1c0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2d1d0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2d1e0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2d1f0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2d200 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2d210 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2d220 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2d230 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2d240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2d250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2d260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d270 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2d280 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2d290 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2d2a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d2b0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2d2c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d2d0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2d2e0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2d2f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2d300 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2d310 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2d320 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2d330 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2d340 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2d350 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2d360 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2d370 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2d380 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2d390 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d3a0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2d3b0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2d3c0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2d3d0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2d3e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2d3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d400 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2d410 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2d420 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2d430 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2d440 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2d450 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d460 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2d470 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2d480 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2d490 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2d4a0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2d4b0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2d4c0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2d4d0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2d4e0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2d4f0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2d500 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2d510 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2d520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d530 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2d540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2d550 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2d560 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2d570 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2d580 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2d590 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2d5a0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2d5b0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2d5c0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2d5d0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2d5e0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2d5f0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2d600 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2d610 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2d620 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2d630 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2d640 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d650 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2d660 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2d670 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2d680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2d690 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2d6a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2d6b0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2d6c0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2d6d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2d6e0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2d6f0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2d700 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2d710 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2d720 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2d730 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2d740 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2d750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2d760 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2d770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2d780 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2d790 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2d7a0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2d7b0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2d7c0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2d7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d7e0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2d7f0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2d800 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2d810 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2d820 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2d830 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2d840 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2d850 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2d860 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2d870 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2d880 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2d890 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2d8a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2d8b0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2d8c0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2d8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d8e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d8f0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2d900 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2d910 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2d920 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2d930 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d940 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d950 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2d960 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d970 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2d980 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2d990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d9a0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2d9b0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2d9c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d9d0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2d9e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2d9f0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2da00 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2da10 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2da20 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2da30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2da40 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2da50 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2da60 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2da70 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2da80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2da90 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2daa0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2dab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2dac0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2dad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2dae0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2daf0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2db00 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2db10 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2db20 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2db30 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2db40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2db50 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2db60 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2db70 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2db80 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2db90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2dba0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2dbb0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dbc0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2dbd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dbe0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2dbf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2dc00 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2dc10 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2dc20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2dc30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2dc40 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2dc50 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2dc60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2dc70 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2dc80 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2dc90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2dca0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2dcb0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2dcc0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2dcd0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2dce0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2dcf0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2dd00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2dd20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2dd30 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2dd40 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2dd50 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2dd60 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2dd70 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2dd80 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2dd90 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2dda0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2ddb0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2ddc0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2ddd0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2dde0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ddf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2de00 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2de10 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2de20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2de30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2de40 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2de50 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2de60 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2de70 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2de80 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2de90 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2dea0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2deb0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2dec0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2ded0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2dee0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2def0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2df00 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2df10 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2df20 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2df30 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2df40 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2df50 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2df60 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2df70 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2df80 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2df90 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2dfa0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2dfb0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2dfc0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2dfd0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2dfe0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2dff0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2e000 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2e010 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2e020 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2e030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2e040 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2e050 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2e060 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2e070 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2e080 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2e090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e0a0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2e0b0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2e0c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2e0d0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2e0e0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2e0f0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2e100 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2e110 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2e120 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2e130 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2e140 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2e150 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2e160 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2e170 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e180 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2e190 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2e1a0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2e1b0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2e1c0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2e1d0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2e1e0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2e1f0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2e200 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e210 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e220 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2e230 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2e240 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2e250 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2e260 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2e270 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2e280 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2e290 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2e2a0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2e2b0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2e2c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2e2d0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2e2e0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2e2f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2e300 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2e310 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2e320 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2e330 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2e340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2e350 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2e360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2e370 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2e380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e390 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2e3a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2e3b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2e3c0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2e3d0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2e3e0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2e3f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2e400 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2e410 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2e420 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2e430 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2e440 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2e450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e460 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2e470 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2e480 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2e490 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2e4a0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2e4b0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2e4c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2e4d0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2e4e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2e4f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2e500 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2e510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e520 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2e530 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2e540 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2e550 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2e560 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2e570 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2e580 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2e590 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2e5a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2e5c0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2e5d0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2e5e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e5f0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2e600 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2e610 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2e620 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2e630 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2e640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e650 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2e660 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2e670 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2e680 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2e690 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2e6a0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2e6b0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2e6c0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2e6d0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2e6e0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2e6f0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2e700 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2e710 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2e720 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2e730 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2e740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2e750 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2e760 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2e770 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2e780 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2e790 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2e7a0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2e7b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2e7c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2e7d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2e7e0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2e7f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2e800 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2e810 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2e820 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2e830 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2e840 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2e850 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2e860 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2e870 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2e880 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2e890 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2e8a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2e8b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2e8c0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2e8d0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2e8e0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2e8f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2e900 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2e910 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2e920 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2e930 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2e940 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2e950 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2e960 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2e970 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2e980 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2e990 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2e9a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2e9b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2e9c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2e9d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2e9e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2e9f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2ea00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2ea10 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2ea20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ea30 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2ea40 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2ea50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ea60 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2ea70 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2ea80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2ea90 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2eaa0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2eab0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2eac0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2ead0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2eae0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2eaf0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2eb00 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2eb10 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2eb20 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2eb30 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2eb40 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2eb50 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2eb60 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2eb70 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2eb80 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2eb90 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2eba0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2ebb0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2ebc0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2ebd0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2ebe0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ebf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ec00 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2ec10 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2ec20 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2ec30 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2ec40 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2ec50 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2ec60 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2ec70 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2ec80 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2ec90 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2eca0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2ecb0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2ecc0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2ecd0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2ece0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2ecf0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2ed00 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2ed10 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2ed20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2ed30 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2ed40 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2ed50 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2ed60 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2ed70 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2ed80 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2ed90 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2eda0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2edb0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49  bind_pointer(S,I
2edc0 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20  ,P,T,D) routine 
2edd0 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20  causes the I-th 
2ede0 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
2edf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ee00 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61  ent] S to have a
2ee10 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e  n SQL value of N
2ee20 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f  ULL, but to also
2ee30 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   be.** associate
2ee40 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74  d with the point
2ee50 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20  er P of type T. 
2ee60 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20   ^D is either a 
2ee70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a  NULL pointer or.
2ee80 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2ee90 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
2eea0 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51  ction for P. ^SQ
2eeb0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2eec0 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74   the.** destruct
2eed0 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
2eee0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50  le argument of P
2eef0 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69   when it is fini
2ef00 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e  shed using.** P.
2ef10 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65    The T paramete
2ef20 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74  r should be a st
2ef30 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65  atic string, pre
2ef40 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67  ferably a string
2ef50 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65  .** literal. The
2ef60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
2ef70 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20  inter() routine 
2ef80 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  is part of the.*
2ef90 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69  * [pointer passi
2efa0 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64  ng interface] ad
2efb0 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33  ded for SQLite 3
2efc0 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  .20.0..**.** ^If
2efd0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2efe0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2eff0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2f000 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2f010 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2f020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f030 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2f040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f050 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2f060 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f070 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2f080 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2f090 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2f0a0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2f0b0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2f0c0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2f0d0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2f0e0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2f0f0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2f100 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f110 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2f120 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2f130 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2f140 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2f150 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2f160 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2f170 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2f180 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2f190 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2f1a0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2f1b0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2f1c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2f1d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2f1e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2f1f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2f200 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2f210 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2f220 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2f230 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2f240 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2f250 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2f260 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2f270 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2f280 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2f290 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2f2a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2f2b0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2f2c0 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2f2d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2f2e0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2f2f0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2f300 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2f310 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2f320 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2f330 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2f340 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2f350 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2f360 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2f370 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2f380 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2f390 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2f3a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2f3b0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2f3c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2f3d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2f3e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f3f0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2f400 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2f410 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2f420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2f430 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f440 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2f450 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2f460 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2f470 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2f480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f490 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2f4a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2f4b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2f4c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2f4d0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
2f4e0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2f4f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2f500 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2f510 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2f520 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2f530 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2f540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f550 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2f560 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
2f570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f580 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2f590 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2f5a0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2f5b0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2f5c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2f5d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2f5e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2f5f0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2f600 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2f610 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2f620 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2f630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2f640 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2f650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f660 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2f670 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2f680 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
2f690 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f6a0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2f6b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2f6c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f6d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f6e0 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65  d_pointer(sqlite
2f6f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f  3_stmt*, int, vo
2f700 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
2f710 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2f720 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2f730 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2f740 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2f750 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
2f760 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2f770 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2f780 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2f790 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
2f7a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2f7b0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2f7c0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2f7d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f7e0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2f7f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2f800 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2f810 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2f820 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2f830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2f840 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2f850 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2f860 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2f870 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2f880 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2f890 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2f8a0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2f8b0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2f8c0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2f8d0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2f8e0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2f8f0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2f900 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2f910 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2f920 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2f930 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2f940 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2f950 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2f960 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2f970 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2f980 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2f990 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2f9a0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2f9b0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2f9c0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2f9d0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2f9e0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2f9f0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2fa00 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2fa10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2fa20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2fa30 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2fa40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2fa50 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2fa60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2fa70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2fa80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2fa90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2faa0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2fab0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2fac0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2fad0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2fae0 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2faf0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2fb00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2fb10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2fb20 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2fb30 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2fb40 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2fb50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2fb60 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2fb70 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2fb80 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2fb90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2fba0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2fbb0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2fbc0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2fbd0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2fbe0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2fbf0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2fc00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2fc10 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2fc20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2fc30 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2fc40 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2fc50 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2fc60 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2fc70 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2fc80 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2fc90 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2fca0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2fcb0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2fcc0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2fcd0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2fce0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2fcf0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2fd00 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2fd10 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2fd20 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2fd30 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2fd40 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2fd50 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2fd60 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2fd70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2fd80 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2fd90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2fda0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2fdb0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2fdc0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2fdd0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2fde0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2fdf0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2fe00 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2fe10 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2fe20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2fe30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2fe40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
2fe50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2fe60 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
2fe70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2fe80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fe90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2fea0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2feb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2fec0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2fed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2fee0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2fef0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2ff00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ff10 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2ff20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2ff30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff40 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2ff50 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2ff60 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
2ff70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ff80 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2ff90 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2ffa0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2ffb0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2ffc0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2ffd0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2ffe0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2fff0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
30000 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
30010 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30020 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
30030 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
30040 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
30050 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
30060 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
30070 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
30080 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
30090 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
300a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
300b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
300c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
300d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
300e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
300f0 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  16_v2()] or.** [
30100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30110 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30120 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30130 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
30140 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30160 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30170 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
30180 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30190 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _name()]..*/.int
301a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
301b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
301c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
301d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
301e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
301f0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
30200 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
30210 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
30220 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30230 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
30240 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
30250 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
30260 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30270 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
30280 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
30290 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
302a0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
302b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
302c0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
302d0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
302e0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
302f0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
30300 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
30310 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
30320 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
30330 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
30340 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
30350 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
30360 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30370 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
30380 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
30390 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
303a0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
303b0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
303c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
303d0 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75  t]. ^If this rou
303e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20  tine returns 0, 
303f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a  that means the .
30400 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30410 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20  tement] returns 
30420 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  no data (for exa
30430 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
30440 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20  )..** ^However, 
30450 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69  just because thi
30460 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
30470 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
30480 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ber does not.** 
30490 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72  mean that one or
304a0 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61   more rows of da
304b0 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  ta will be retur
304c0 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20  ned.  ^A SELECT 
304d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c  statement.** wil
304e0 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20  l always have a 
304f0 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33  positive sqlite3
30500 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20  _column_count() 
30510 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  but depending on
30520 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c   the.** WHERE cl
30530 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
30540 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63   and the table c
30550 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74  ontent, it might
30560 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e   return no rows.
30570 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
30580 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
30590 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
305a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
305b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
305c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
305d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
305e0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
305f0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
30600 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30610 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
30620 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
30630 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
30640 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
30650 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
30660 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
30670 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
30680 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
30690 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
306a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
306b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
306c0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
306d0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
306e0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
306f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
30700 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
30710 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
30720 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
30730 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
30740 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
30750 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
30760 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
30770 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
30780 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
30790 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
307a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
307b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
307c0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
307d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
307e0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
307f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
30800 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
30810 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
30820 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30830 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
30840 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
30850 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30860 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
30870 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
30880 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
30890 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
308a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
308b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
308c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
308d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
308e0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
308f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30900 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
30910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
30920 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
30930 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
30940 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
30950 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
30960 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
30970 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
30980 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
30990 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
309a0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
309b0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
309c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
309d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
309e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
309f0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
30a00 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
30a10 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
30a20 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
30a30 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
30a40 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
30a50 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
30a60 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
30a70 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
30a80 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
30a90 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
30aa0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
30ab0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
30ac0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
30ad0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
30ae0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30af0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
30b00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
30b10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30b20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
30b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30b40 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
30b50 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
30b60 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
30b70 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
30b80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30b90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
30ba0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
30bb0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
30bc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
30bd0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
30be0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
30bf0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
30c00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
30c10 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
30c20 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
30c30 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
30c40 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
30c50 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
30c60 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
30c70 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
30c80 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
30c90 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
30ca0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
30cb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
30cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
30cd0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
30ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
30cf0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
30d00 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
30d10 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
30d20 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
30d30 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
30d40 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
30d50 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
30d60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30d70 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
30d80 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
30d90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
30da0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
30db0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
30dc0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
30dd0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
30de0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30df0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
30e00 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
30e10 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
30e20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
30e30 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
30e40 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
30e50 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
30e60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
30e70 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
30e80 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
30e90 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
30ea0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
30eb0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
30ec0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
30ed0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
30ee0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
30ef0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
30f00 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30f10 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30f20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
30f30 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
30f40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
30f50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
30f60 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
30f70 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
30f80 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
30f90 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
30fa0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
30fb0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
30fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
30fd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
30fe0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
30ff0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
31000 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
31010 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
31020 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
31030 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
31040 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
31050 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
31060 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
31070 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
31080 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
31090 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
310a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
310b0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
310c0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
310d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
310e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
310f0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
31100 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
31110 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
31120 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
31130 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
31140 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
31150 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
31160 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
31170 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
31180 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
31190 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
311a0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
311b0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
311c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
311d0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
311e0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
311f0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
31200 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
31210 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
31220 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
31230 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
31240 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
31250 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
31260 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
31270 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
31280 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
31290 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
312a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
312b0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
312c0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
312d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
312e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
312f0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
31300 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
31310 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
31320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31330 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
31340 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
31350 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
31360 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
31370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
31380 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
31390 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
313a0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
313b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
313c0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
313d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
313e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
313f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31400 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
31410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
31420 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
31430 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31440 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
31450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
31460 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
31470 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31480 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31490 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
314a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
314b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
314c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
314d0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
314e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
314f0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
31500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
31510 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
31520 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31540 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
31550 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
31560 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
31570 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31580 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
31590 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
315a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
315b0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
315c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
315d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
315e0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
315f0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
31600 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
31610 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
31620 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
31630 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
31640 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
31650 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
31660 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
31670 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
31680 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
31690 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
316a0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
316b0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
316c0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
316d0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
316e0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
316f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
31700 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31710 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
31720 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
31730 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
31740 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
31750 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
31760 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
31770 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
31780 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
31790 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
317a0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
317b0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
317c0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
317d0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
317e0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
317f0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
31800 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
31810 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
31820 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
31830 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
31840 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
31850 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
31860 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
31870 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
31880 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
31890 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
318a0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
318b0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
318c0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
318d0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
318e0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
318f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
31900 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
31910 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
31920 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
31930 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
31940 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
31950 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
31960 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
31970 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
31980 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
31990 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
319a0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
319b0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
319c0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
319d0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
319e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
319f0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
31a00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31a10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
31a30 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
31a40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
31a50 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
31a60 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
31a70 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
31a80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31a90 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
31aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31ab0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
31ac0 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a  ed using any of.
31ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
31ae0 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
31af0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
31b00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
31b10 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
31b20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
31b30 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f  are16_v3()] or o
31b40 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
31b50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
31b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
31b70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
31b80 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
31b90 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
31ba0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
31bb0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
31bc0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
31bd0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
31be0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
31bf0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
31c00 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
31c10 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
31c20 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
31c30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
31c40 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
31c50 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22  g the newer "vX"
31c60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b   interfaces.** [
31c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31c80 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
31c90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
31ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31cb0 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  6_v3()],.** [sql
31cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
31cd0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
31ce0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
31cf0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
31d00 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
31d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31d20 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
31d30 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58  f the.** new "vX
31d40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
31d50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
31d60 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
31d70 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
31d80 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
31d90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
31da0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
31db0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
31dc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
31dd0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
31de0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
31df0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
31e00 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
31e10 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
31e20 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
31e30 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
31e40 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
31e50 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
31e60 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
31e70 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
31e80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
31e90 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
31ea0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
31eb0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
31ec0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
31ed0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
31ee0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
31ef0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
31f00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
31f10 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
31f20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
31f30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31f40 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
31f50 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
31f60 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
31f70 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
31f80 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
31f90 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
31fa0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
31fb0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
31fc0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
31fd0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
31fe0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
31ff0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
32000 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
32010 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
32020 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
32030 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
32040 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
32050 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
32060 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
32070 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
32080 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
32090 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
320a0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
320b0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
320c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
320d0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
320e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
320f0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
32100 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
32110 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
32120 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
32130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
32150 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
32160 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
32170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
32180 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
32190 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
321a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
321b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
321c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
321d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
321e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
321f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
32200 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
32210 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
32220 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
32230 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
32240 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
32250 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
32260 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
32270 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
32280 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
32290 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
322a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
322b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
322c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
322d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
322e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
322f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
32300 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
32310 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
32320 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
32330 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
32340 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
32350 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
32360 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
32370 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
32380 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
32390 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
323a0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
323b0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
323c0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
323d0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
323e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
323f0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
32400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32410 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
32420 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
32430 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
32440 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
32450 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
32460 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
32470 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
32480 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
32490 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
324a0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
324b0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
324c0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
324d0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
324e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
324f0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
32500 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
32510 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32520 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
32530 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
32540 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
32550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
32560 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
32570 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
32580 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
32590 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
325a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
325b0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
325c0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
325d0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
325e0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
325f0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
32600 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
32610 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
32620 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
32630 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
32640 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32650 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
32660 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
32670 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
32680 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
32690 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
326a0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
326b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
326c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
326d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
326e0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
326f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
32700 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
32710 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
32720 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
32730 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
32740 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
32750 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
32760 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
32770 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33   [version 3.6.23
32780 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36  .1] ([dateof:3.6
32790 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74  .23.1],.** sqlit
327a0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
327b0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
327c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
327d0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
327e0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
327f0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
32800 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
32810 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
32820 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
32830 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
32840 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
32850 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
32860 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
32870 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
32880 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
32890 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
328a0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
328b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
328c0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
328d0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
328e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
328f0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
32900 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
32910 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
32920 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
32930 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
32940 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
32950 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
32960 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
32970 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
32980 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
32990 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
329a0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
329b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
329c0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
329d0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
329e0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
329f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
32a00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32a10 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
32a20 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
32a30 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
32a40 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
32a50 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
32a60 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
32a70 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
32a80 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
32a90 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
32aa0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
32ab0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
32ac0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
32ad0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
32ae0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
32af0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
32b00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
32b10 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v3()] or [sql
32b20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32b30 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
32b40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
32b50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
32b60 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
32b70 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
32b80 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
32b90 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
32ba0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32bb0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
32bc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
32bd0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
32be0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
32bf0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
32c00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
32c10 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
32c20 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66   the "vX" interf
32c30 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e  aces is recommen
32c40 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
32c50 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
32c60 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32c70 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
32c80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
32c90 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
32ca0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32cb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
32cc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
32cd0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
32ce0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32cf0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
32d00 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
32d10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
32d20 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
32d30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
32d40 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
32d50 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
32d60 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
32d70 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
32d80 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
32d90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
32da0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
32db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
32dc0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
32dd0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
32de0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
32df0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
32e00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
32e10 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
32e20 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
32e30 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
32e40 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
32e50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
32e60 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
32e70 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
32e80 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
32e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32ea0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
32eb0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
32ec0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
32ed0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
32ee0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
32ef0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
32f00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
32f10 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
32f20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
32f30 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
32f40 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
32f50 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
32f60 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
32f70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
32f80 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
32f90 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
32fa0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
32fb0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
32fc0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
32fd0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
32fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
32ff0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
33000 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33010 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33020 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33030 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
33040 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
33050 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
33060 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
33070 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
33080 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
33090 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
330a0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
330b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
330c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
330d0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
330e0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
330f0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
33100 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
33110 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
33120 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
33130 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
33140 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
33150 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
33160 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
33170 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
33180 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
33190 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
331a0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
331b0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
331c0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
331d0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
331e0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
331f0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
33200 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
33210 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
33220 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
33230 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
33240 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
33250 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
33260 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
33270 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
33280 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
33290 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
332a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
332b0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
332c0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
332d0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
332e0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
332f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
33300 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
33310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
33320 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
33330 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
33340 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
33350 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
33360 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
33370 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
33380 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33390 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75  stmt.**.** <b>Su
333a0 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62  mmary:</b>.** <b
333b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65  lockquote><table
333c0 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61   border=0 cellpa
333d0 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63  dding=0 cellspac
333e0 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=0>.** <tr><t
333f0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33400 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e  umn_blob</b><td>
33410 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72  &rarr;<td>BLOB r
33420 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
33430 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33440 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64  mn_double</b><td
33450 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20  >&rarr;<td>REAL 
33460 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33470 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33480 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26  umn_int</b><td>&
33490 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20  rarr;<td>32-bit 
334a0 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
334b0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
334c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
334d0 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  4</b><td>&rarr;<
334e0 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45  td>64-bit INTEGE
334f0 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
33500 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33510 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74  olumn_text</b><t
33520 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
33530 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  8 TEXT result.**
33540 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
33550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33560 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  6</b><td>&rarr;<
33570 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72  td>UTF-16 TEXT r
33580 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
33590 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
335a0 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e  mn_value</b><td>
335b0 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65  &rarr;<td>The re
335c0 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b  sult as an .** [
335d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e  sqlite3_value|un
335e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
335f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
33600 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73  .** <tr><td>&nbs
33610 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  p;<td>&nbsp;<td>
33620 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74  &nbsp;.** <tr><t
33630 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33640 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64  umn_bytes</b><td
33650 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20  >&rarr;<td>Size 
33660 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20  of a BLOB.** or 
33670 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  a UTF-8 TEXT res
33680 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  ult in bytes.** 
33690 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
336a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
336b0 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62  6&nbsp;&nbsp;</b
336c0 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26  >.** <td>&rarr;&
336d0 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53  nbsp;&nbsp;<td>S
336e0 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a  ize of UTF-16.**
336f0 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a   TEXT in bytes.*
33700 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33720 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
33730 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74  d>Default.** dat
33740 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73  atype of the res
33750 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c  ult.** </table><
33760 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
33770 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f  ** <b>Details:</
33780 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  b>.**.** ^These 
33790 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
337a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
337b0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
337c0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
337d0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
337e0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
337f0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
33800 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
33810 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
33820 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33830 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
33840 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
33850 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
33860 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
33870 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
33880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33890 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
338a0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
338b0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
338c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
338d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
338e0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
338f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
33900 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
33910 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
33920 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
33930 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
33940 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
33950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
33960 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
33970 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
33980 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
33990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
339a0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
339b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
339c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
339d0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
339e0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
339f0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
33a00 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
33a10 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
33a20 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
33a30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33a40 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
33a50 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
33a60 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
33a70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
33a80 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
33a90 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
33aa0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
33ab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33ac0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
33ad0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
33ae0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
33af0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
33b00 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
33b10 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
33b20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
33b30 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
33b40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33b50 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
33b60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
33b70 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
33b80 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
33b90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
33ba0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
33bb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
33bc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33bd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
33be0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
33bf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
33c00 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
33c10 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
33c20 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
33c30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33c40 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
33c50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
33c60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
33c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
33c80 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20   six interfaces 
33c90 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c  (_blob, _double,
33ca0 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f   _int, _int64, _
33cb0 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31  text, and _text1
33cc0 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72  6).** each retur
33cd0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  n the value of a
33ce0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
33cf0 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  n a specific dat
33d00 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a  a format.  If.**
33d10 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
33d20 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61  mn is not initia
33d30 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65  lly in the reque
33d40 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72  sted format (for
33d50 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20   example,.** if 
33d60 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e  the query return
33d70 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74  s an integer but
33d80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
33d90 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72  umn_text() inter
33da0 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20  face.** is used 
33db0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76  to extract the v
33dc0 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75  alue) then an au
33dd0 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
33de0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
33df0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
33e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33e10 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
33e20 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
33e30 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
33e40 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
33e50 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
33e60 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
33e70 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
33e80 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
33e90 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
33ea0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
33eb0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
33ec0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
33ed0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
33ee0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
33ef0 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74  ULL]..** The ret
33f00 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c  urn value of sql
33f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33f20 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  () can be used t
33f30 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a  o decide which.*
33f40 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73  * of the first s
33f50 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ix interface sho
33f60 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65  uld be used to e
33f70 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d  xtract the colum
33f80 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20  n value..** The 
33f90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
33fa0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
33fb0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
33fc0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
33fd0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79  .** automatic ty
33fe0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  pe conversions h
33ff0 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72  ave occurred for
34000 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75   the value in qu
34010 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74  estion.  .** Aft
34020 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
34030 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74  sion, the result
34040 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   of calling sqli
34050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34060 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
34070 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65  d, though harmle
34080 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ss.  Future.** v
34090 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
340a0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
340b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
340c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
340d0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
340e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
340f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
34100 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
34110 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e   or a TEXT strin
34120 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  g, then the sqli
34130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34140 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34160 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e  ) interfaces can
34170 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65   be used to dete
34180 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a  rmine the size.*
34190 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f  * of that BLOB o
341a0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  r string..**.** 
341b0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
341c0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
341d0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
341e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
341f0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
34200 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
34210 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34220 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
34230 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
34240 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
34250 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
34260 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34270 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
34280 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
34290 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
342a0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
342b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
342c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
342d0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
342e0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
342f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34300 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
34310 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
34320 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
34330 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
34340 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
34350 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
34360 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
34370 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34380 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
34390 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
343a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
343b0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
343c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
343d0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
343e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
343f0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34400 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
34410 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
34420 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
34430 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
34440 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
34450 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34460 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
34470 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
34480 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34490 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
344a0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
344b0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
344c0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
344d0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
344e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
344f0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
34500 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34510 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
34520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34530 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34540 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34550 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
34560 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
34570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34580 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
34590 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
345a0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
345b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
345c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
345d0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
345e0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
345f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
34600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34610 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
34620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34630 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
34640 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
34650 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
34660 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
34670 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
34680 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
34690 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
346a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
346b0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
346c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
346d0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
346e0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
346f0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
34700 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
34710 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
34720 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
34730 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
34740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
34750 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
34760 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
34770 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
34780 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
34790 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
347a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
347b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
347c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
347d0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
347e0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
347f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
34800 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
34810 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
34820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
34830 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
34840 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
34850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34860 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
34870 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
34880 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
34890 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
348a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
348b0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
348c0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
348d0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
348e0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
348f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
34900 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
34910 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
34920 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34930 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
34940 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
34950 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
34960 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
34970 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
34980 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
34990 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
349a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
349b0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
349c0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
349d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
349e0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
349f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
34a00 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
34a10 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69   Hence, the sqli
34a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
34a30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
34a40 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79  is normally only
34a50 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74   useful within t
34a60 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34a70 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63  n of .** [applic
34a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34a90 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20  L functions] or 
34aa0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
34ab0 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20  , not within.** 
34ac0 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63  top-level applic
34ad0 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  ation code..**.*
34ae0 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74  * The these rout
34af0 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74  ines may attempt
34b00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
34b10 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
34b20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20  result..** ^For 
34b30 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
34b40 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
34b50 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
34b60 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
34b70 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
34b80 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
34b90 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
34ba0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
34bb0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
34bc0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
34bd0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
34be0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
34bf0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
34c00 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
34c10 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
34c20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
34c30 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
34c40 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
34c50 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
34c60 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
34c70 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
34c80 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
34c90 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
34ca0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
34cb0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
34cc0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
34cd0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
34ce0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
34cf0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
34d00 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
34d10 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
34d20 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
34d30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
34d40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
34d50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
34d60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
34d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
34d80 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
34d90 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
34da0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
34db0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
34dc0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
34dd0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
34de0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
34df0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
34e00 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
34e10 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
34e20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
34e30 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
34e40 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
34e50 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
34e60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
34e70 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
34e80 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
34e90 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
34ea0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
34eb0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
34ec0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
34ed0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
34ee0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
34ef0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
34f00 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
34f10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
34f20 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
34f30 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
34f40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
34f50 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
34f60 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
34f70 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
34f80 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
34f90 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
34fa0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
34fb0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
34fc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
34fd0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
34fe0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
34ff0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
35000 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35010 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35020 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35030 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35040 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
35050 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
35060 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
35070 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
35080 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
35090 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
350a0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
350b0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
350c0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
350d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
350e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
350f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35100 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
35110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35120 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
35130 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
35140 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
35150 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
35160 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
35170 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
35180 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
35190 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
351a0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
351b0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
351c0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
351d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
351e0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
351f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
35200 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
35210 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
35220 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
35230 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
35240 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
35250 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
35260 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
35270 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
35280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35290 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
352a0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
352b0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
352c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
352d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
352e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
352f0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
35300 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35310 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
35320 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
35330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35340 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35360 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
35370 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
35380 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
35390 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
353a0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
353b0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
353c0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
353d0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
353e0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
353f0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
35400 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
35410 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
35420 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
35430 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
35440 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
35450 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
35460 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
35470 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
35480 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
35490 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
354a0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
354b0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
354c0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
354d0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
354e0 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
354f0 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
35500 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
35510 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
35520 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
35530 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
35540 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
35550 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
35560 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
35570 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
35580 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
35590 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
355a0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
355b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
355c0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
355d0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
355e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
355f0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
35600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35610 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
35620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35630 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
35640 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
35650 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
35660 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
35670 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
35680 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
35690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
356a0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
356b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
356c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
356d0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
356e0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
356f0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
35700 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
35710 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
35720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35730 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
35740 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35750 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
35760 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
35770 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
35780 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
35790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
357a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
357b0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
357c0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
357d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
357e0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
357f0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
35800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35810 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
35820 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
35830 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
35840 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
35850 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
35860 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
35870 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
35880 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
35890 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
358a0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
358b0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
358c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
358d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
358e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
358f0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
35900 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
35910 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
35920 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
35930 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
35940 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f   not pass the po
35950 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
35960 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
35970 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
35980 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35990 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
359a0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
359b0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
359c0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
359d0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
359e0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
359f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
35a00 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
35a10 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
35a20 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
35a30 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
35a40 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
35a50 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
35a60 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
35a70 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
35a80 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
35a90 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
35aa0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
35ab0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
35ac0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
35ad0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
35ae0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
35af0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
35b00 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
35b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35b20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
35b30 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
35b40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
35b50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
35b60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
35b70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
35b80 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
35b90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
35ba0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
35bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
35bc0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
35bd0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
35be0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
35bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
35c00 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
35c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
35c20 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
35c30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
35c40 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
35c50 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
35c60 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
35c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
35c80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
35c90 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
35ca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
35cb0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
35cc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
35ce0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
35cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
35d00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
35d10 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
35d20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
35d30 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
35d40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
35d50 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
35d60 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
35d70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35d80 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
35d90 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
35da0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
35db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
35dc0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
35dd0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
35de0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
35df0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
35e00 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
35e10 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
35e20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
35e30 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
35e40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
35e60 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
35e70 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
35e80 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
35e90 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
35ea0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
35eb0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
35ec0 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
35ed0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
35ee0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
35ef0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
35f00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
35f10 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
35f20 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
35f30 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
35f40 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
35f50 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
35f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
35f70 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
35f80 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
35f90 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
35fa0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
35fb0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
35fc0 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
35fd0 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
35fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
35ff0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
36000 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
36010 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
36020 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
36030 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
36040 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
36050 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
36060 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36070 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
36080 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
36090 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
360a0 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
360b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
360c0 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
360d0 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
360e0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
360f0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
36100 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
36110 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
36120 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
36130 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
36140 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
36150 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
36160 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
36170 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
36180 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
36190 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
361a0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
361b0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
361c0 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
361d0 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
361e0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
361f0 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
36200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
36210 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36220 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36230 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
36240 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
36250 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
36260 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36270 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
36280 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
36290 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
362a0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
362b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
362c0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
362d0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
362e0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
362f0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
36300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
36310 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
36320 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
36330 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
36340 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
36350 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
36360 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
36370 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
36380 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
36390 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
363a0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
363b0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
363c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
363d0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
363e0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
363f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36400 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
36410 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
36420 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
36430 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
36440 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
36450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36460 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
36470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36480 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
36490 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
364a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
364b0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
364c0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
364d0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
364e0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
364f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
36500 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
36510 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
36520 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36530 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
36540 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
36550 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
36560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36570 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
36580 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
36590 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
365a0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
365b0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
365c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
365d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
365e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
365f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
36600 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
36610 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
36620 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
36630 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
36640 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
36650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
36660 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
36670 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
36680 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
36690 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
366a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
366b0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
366c0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
366d0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
366e0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
366f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
36700 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
36710 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
36720 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
36730 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
36740 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
36750 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
36760 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
36770 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
36780 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
36790 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
367a0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
367b0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
367c0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
367d0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
367e0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
367f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
36800 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
36810 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
36820 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
36830 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36840 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
36850 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
36860 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
36870 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
36880 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
36890 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
368a0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
368b0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
368c0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
368d0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
368e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
368f0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
36900 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
36910 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
36920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36930 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
36940 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
36950 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
36960 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
36970 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
36980 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
36990 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
369a0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
369b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
369c0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
369d0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
369e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
369f0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
36a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
36a10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
36a20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
36a30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
36a40 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
36a50 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
36a60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
36a70 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
36a80 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
36a90 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
36aa0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
36ab0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
36ac0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
36ad0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
36ae0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
36af0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
36b00 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
36b10 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
36b20 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
36b30 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
36b40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
36b50 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
36b60 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
36b70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
36b80 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
36b90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
36ba0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
36bb0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
36bc0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
36bd0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
36be0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
36bf0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
36c00 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
36c10 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
36c20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
36c30 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
36c40 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
36c50 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
36c60 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
36c70 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
36c80 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
36c90 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
36ca0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
36cb0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
36cc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
36cd0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
36ce0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
36cf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36d00 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
36d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
36d20 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
36d30 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
36d40 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
36d50 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
36d60 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
36d70 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
36d80 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
36d90 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
36da0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
36db0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
36dc0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
36dd0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
36de0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
36df0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
36e00 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
36e10 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
36e20 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
36e30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
36e40 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
36e50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
36e60 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
36e70 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
36e80 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
36e90 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
36ea0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
36eb0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
36ec0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
36ed0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
36ee0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
36ef0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
36f00 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
36f10 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
36f20 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
36f30 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
36f40 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
36f50 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
36f60 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
36f70 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
36f80 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
36f90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36fa0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
36fb0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
36fc0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
36fd0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
36fe0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
36ff0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37000 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
37010 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
37020 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
37030 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
37040 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
37050 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
37060 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
37070 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
37080 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
37090 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
370a0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
370b0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
370c0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
370d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
370e0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
370f0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
37100 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
37110 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
37120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
37130 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
37140 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
37150 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
37160 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
37170 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
37180 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
37190 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
371a0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
371b0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
371c0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
371d0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
371e0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
371f0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
37200 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
37210 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
37220 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
37230 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
37240 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
37250 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37260 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
37270 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
37280 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
37290 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
372a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
372b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
372c0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
372d0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
372e0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
372f0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
37300 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
37310 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
37320 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
37330 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
37340 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37350 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
37360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
37370 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
37380 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
37390 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
373a0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
373b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
373c0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
373d0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
373e0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
373f0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
37400 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
37410 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37420 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
37430 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
37440 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
37450 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
37460 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
37470 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
37480 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
37490 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
374a0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
374b0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
374c0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
374d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
374e0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
374f0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
37500 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
37510 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
37520 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
37530 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
37540 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
37550 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
37560 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
37570 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
37580 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
37590 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
375a0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
375b0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
375c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
375d0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
375e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
375f0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
37600 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
37610 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37620 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
37630 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
37640 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
37650 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
37660 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
37670 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
37680 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
37690 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
376a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
376b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
376c0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
376d0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
376e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
376f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37700 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
37710 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
37720 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
37730 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
37740 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
37750 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
37760 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
37770 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
37780 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
37790 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
377a0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
377b0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
377c0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
377d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
377e0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
377f0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
37800 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
37810 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
37820 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
37830 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
37840 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
37850 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
37860 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
37870 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
37880 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
37890 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
378a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
378b0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
378c0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
378d0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
378e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
378f0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
37900 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
37910 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
37920 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
37930 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
37940 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
37950 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
37960 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
37970 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
37980 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
37990 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
379a0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
379b0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
379c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
379d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
379e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
379f0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
37a00 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
37a10 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
37a20 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
37a30 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
37a40 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
37a50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
37a60 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
37a70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37a80 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
37a90 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
37aa0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
37ab0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
37ac0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
37ad0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
37ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37af0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
37b00 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
37b10 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
37b20 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
37b30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
37b40 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
37b50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37b60 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
37b70 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
37b80 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
37b90 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
37ba0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
37bb0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
37bc0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
37bd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37be0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
37bf0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
37c00 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
37c10 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
37c20 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
37c30 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
37c40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37c50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
37c60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
37c70 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
37c80 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
37c90 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
37ca0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
37cb0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
37cc0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
37cd0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
37ce0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
37cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
37d00 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
37d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37d20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
37d30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
37d40 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
37d50 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
37d60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37d70 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
37d80 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
37d90 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
37da0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
37db0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
37dc0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
37dd0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
37de0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
37df0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
37e00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
37e10 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
37e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
37e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
37e40 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
37e50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
37e60 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
37e70 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
37e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37e90 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
37ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
37eb0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
37ec0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
37ed0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
37ee0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
37ef0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
37f00 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
37f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
37f20 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
37f30 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
37f40 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
37f50 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
37f60 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
37f70 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
37f80 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
37f90 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
37fa0 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
37fb0 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
37fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37fd0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
37fe0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
37ff0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
38000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38010 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
38020 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
38030 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
38040 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
38050 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
38060 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
38070 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
38080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
38090 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
380a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
380b0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
380c0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
380d0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
380e0 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
380f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
38100 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
38110 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
38120 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38130 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
38140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38150 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
38160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
38170 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
38180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
38190 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
381a0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
381b0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
381c0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
381d0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
381e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
381f0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
38200 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
38210 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
38220 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
38230 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
38240 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
38250 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
38260 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
38270 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
38280 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
38290 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
382a0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
382b0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63  nctions.  To enc
382c0 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65  ourage programme
382d0 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  rs to avoid.** t
382e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
382f0 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c  we will not expl
38300 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f  ain what they do
38310 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
38320 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
38330 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
38340 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
38350 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
38360 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
38370 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
38380 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
38390 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
383a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
383b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
383c0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
383d0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
383e0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
383f0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
38400 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
38410 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
38420 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
38430 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
38440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
38450 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
38460 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
38470 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
38480 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
38490 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
384a0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
384b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
384c0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
384d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
384e0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
384f0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
38500 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
38510 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
38520 65 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61  e.**.** <b>Summa
38530 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63  ry:</b>.** <bloc
38540 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f  kquote><table bo
38550 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69  rder=0 cellpaddi
38560 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67  ng=0 cellspacing
38570 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  =0>.** <tr><td><
38580 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  b>sqlite3_value_
38590 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  blob</b><td>&rar
385a0 72 3b 3c 74 64 3e 42 4c 4f 42 20 76 61 6c 75 65  r;<td>BLOB value
385b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
385c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
385d0 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
385e0 3b 3c 74 64 3e 52 45 41 4c 20 76 61 6c 75 65 0a  ;<td>REAL value.
385f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
38600 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 3c  lite3_value_int<
38610 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
38620 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >32-bit INTEGER 
38630 76 61 6c 75 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  value.** <tr><td
38640 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75  ><b>sqlite3_valu
38650 65 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26  e_int64</b><td>&
38660 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20  rarr;<td>64-bit 
38670 49 4e 54 45 47 45 52 20 76 61 6c 75 65 0a 2a 2a  INTEGER value.**
38680 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
38690 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65  te3_value_pointe
386a0 72 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  r</b><td>&rarr;<
386b0 74 64 3e 50 6f 69 6e 74 65 72 20 76 61 6c 75 65  td>Pointer value
386c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
386d0 71 6c 69 74 65 33 5f 7