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

Artifact 2b39137bc2262f9e414c76e846c28abf3755eaf13275d0b84b9a4593ce7f84a8:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
66c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
66d0: 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f  EN_FILEPROTECTIO
66e0: 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 20 20 20  N_MASK          
66f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6700: 20 20 20 20 20 20 20 30 78 30 30 37 30 30 30 30         0x0070000
6710: 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  0../* Reserved: 
6720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6730: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6740: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6750: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6760: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6770: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6780: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6790: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
67a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
67b0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
67c0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
67d0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
67e0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
67f0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6800: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6810: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
6820: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6830: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6840: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6850: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6860: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6870: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
68a0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
68b0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
68c0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
68d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
68e0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
68f0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6900: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6910: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
6920: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6930: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6940: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6950: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6960: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6970: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6980: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6990: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
69a0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
69b0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
69c0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
69d0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
69e0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
69f0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6a00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6a10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
6a20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6a30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6a40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6a50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6a60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6a70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6a80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6a90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6aa0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6ab0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6ac0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6ad0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6ae0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6af0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6b00: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6b10: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
6b20: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6b30: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6b40: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6b50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6b60: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6b70: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6b80: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6b90: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6ba0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6bb0: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6bc0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6bd0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6be0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6bf0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6c00: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6c10: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
6c20: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6c30: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6c40: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6c50: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6c60: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6c70: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6c80: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6c90: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6ca0: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6cb0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6cc0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6cd0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ges..**.** The S
6ce0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
6cf0: 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  H_ATOMIC propert
6d00: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  y means that the
6d10: 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66   underlying.** f
6d20: 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72  ilesystem suppor
6d30: 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c  ts doing multipl
6d40: 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  e write operatio
6d50: 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68  ns atomically wh
6d60: 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74  en those.** writ
6d70: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
6d80: 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53   bracketed by [S
6d90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
6da0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
6db0: 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  and.** [SQLITE_F
6dc0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
6dd0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64  IC_WRITE]..*/.#d
6de0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6df0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6e00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6e10: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e30: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6e40: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6e60: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6e70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6e80: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6e90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6eb0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ed0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6ee0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6ef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6f00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6f20: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
6f30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6f40: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6f50: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6f70: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6f80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f90: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6fa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6fb0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6fc0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6fe0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6ff0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7000: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
7010: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7020: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
7030: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
7040: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7050: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
7060: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
7070: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7080: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
7090: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
70a0: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
70b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
70c0: 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  MUTABLE         
70d0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
70e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
70f0: 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49  OCAP_BATCH_ATOMI
7100: 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  C           0x00
7110: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
7120: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
7130: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
7140: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
7150: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
7160: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
7170: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
7180: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
7190: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
71a0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
71b0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
71c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
71d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
71e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
71f0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
7200: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
7210: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7220: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
7230: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7240: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
7250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7260: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
7270: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7280: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7290: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
72a0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
72b0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
72c0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
72d0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
72e0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
72f0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
7300: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7310: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
7320: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
7330: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
7340: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7350: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
7360: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
7370: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7380: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
7390: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
73a0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
73b0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
73c0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
73d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
73e0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
73f0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
7400: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
7410: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7420: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
7430: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7440: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
7450: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
7460: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
7470: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
7480: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7490: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
74a0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
74b0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
74c0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
74d0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
74e0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
74f0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
7500: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7510: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7520: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7530: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
7540: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7550: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
7560: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
7570: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
7580: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
7590: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
75a0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
75b0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
75c0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
75d0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
75e0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
75f0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7600: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7610: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7620: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7630: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
7640: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
7650: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
7660: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
7670: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7680: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7690: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
76a0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
76b0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
76c0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
76d0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
76e0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
76f0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7700: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7710: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7720: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7730: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
7740: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
7750: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
7760: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
7770: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7780: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7790: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
77a0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
77b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
77c0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
77d0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
77e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
77f0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7800: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7810: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7820: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7830: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7840: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
7850: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
7860: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
7870: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7880: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7890: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
78a0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
78b0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
78c0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
78d0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
78e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
78f0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7900: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7910: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7920: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7930: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
7940: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
7950: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
7960: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
7970: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7980: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7990: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
79a0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
79b0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
79c0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
79d0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
79e0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
79f0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7a00: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7a10: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7a20: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7a30: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
7a40: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
7a50: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
7a60: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
7a70: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7a80: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7a90: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7aa0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7ab0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7ac0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7ad0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7ae0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7af0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7b00: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7b10: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7b20: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7b30: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7b40: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7b50: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7b60: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7b70: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7b80: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7b90: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7ba0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7bb0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7bc0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7bd0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7be0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7bf0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7c00: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7c10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7c20: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7c30: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7c40: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7c50: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7c60: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7c70: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7c80: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7c90: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7ca0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7cb0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7cc0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7cd0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7ce0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7cf0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7d00: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7d10: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7d20: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7d30: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7d40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7d50: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7d60: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7d70: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7d80: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7d90: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7da0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7db0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7dc0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7dd0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7de0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7df0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7e00: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7e10: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7e20: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7e30: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7e40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7e50: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7e60: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7e70: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7e80: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7e90: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7ea0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7eb0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7ec0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7ed0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7ee0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7ef0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7f00: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7f10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7f20: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7f30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7f40: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7f50: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7f60: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7f70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7f80: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7f90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7fa0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7fb0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7fc0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7fd0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7fe0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7ff0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
8000: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
8010: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
8020: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
8030: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
8040: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
8050: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
8060: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
8070: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
8080: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
8090: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
80a0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
80b0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
80c0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
80d0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
80e0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
80f0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
8100: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
8110: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
8120: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
8130: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
8140: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
8150: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
8160: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
8170: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
8180: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8190: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
81a0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
81b0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
81c0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
81d0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
81e0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
81f0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
8200: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
8210: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
8220: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
8230: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
8240: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
8250: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
8260: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
8270: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
8280: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
8290: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
82a0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
82b0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
82c0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
82d0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
82e0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
82f0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
8300: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
8310: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
8320: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
8330: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
8340: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
8350: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
8360: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
8370: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
8380: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
8390: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
83a0: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
83b0: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
83c0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
83d0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
83e0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
83f0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
8400: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8410: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
8420: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
8430: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
8440: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
8450: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
8460: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
8470: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
8480: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
8490: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
84a0: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
84b0: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
84c0: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
84d0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
84e0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
84f0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
8500: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8510: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8520: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8530: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
8540: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
8550: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
8560: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
8570: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8580: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8590: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
85a0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
85b0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
85c0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
85d0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
85e0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
85f0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8600: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8610: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8620: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8630: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8640: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
8650: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8660: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
8670: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8680: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8690: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
86b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
86d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
86f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8700: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8710: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8720: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8730: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
8740: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8750: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
8760: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
8770: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69  QUENTIAL].** <li
8780: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8790: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
87a0: 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  _OPEN].** <li> [
87b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
87c0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
87d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87e0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
87f0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8800: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
8810: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  TOMIC].** </ul>.
8820: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
8840: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8850: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
8860: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
8870: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
88a0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
88b0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
88c0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
88d0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
88e0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
88f0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8900: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8910: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8920: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8930: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8940: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8950: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8960: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8970: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
8980: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
8990: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
89a0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
89b0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
89c0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
89d0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
89e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
89f0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8a00: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8a10: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8a20: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8a30: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8a40: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8a50: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8a60: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8a70: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
8a80: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
8a90: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
8aa0: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
8ab0: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
8ac0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
8ad0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8ae0: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8af0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8b00: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8b10: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8b20: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8b30: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8b40: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8b50: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8b60: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8b70: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
8b80: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8b90: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
8ba0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
8bb0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8bc0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
8bd0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8be0: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8bf0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8c00: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8c10: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8c20: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8c30: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8c40: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8c50: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8c60: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8c70: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8c80: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8c90: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
8ca0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8cb0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
8cc0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
8cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ce0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8cf0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8d00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8d10: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8d20: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8d30: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8d40: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8d50: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8d60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8d70: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
8d80: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
8d90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
8da0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8db0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
8dc0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8dd0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8de0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8df0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8e00: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8e10: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8e20: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8e30: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8e40: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8e50: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8e60: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8e70: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
8e80: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
8e90: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
8ea0: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
8eb0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
8ec0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ed0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8ee0: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8ef0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8f00: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8f10: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8f20: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8f30: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8f40: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8f50: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8f60: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8f70: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8f80: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8f90: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8fa0: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8fb0: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8fc0: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8fd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8fe0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8ff0: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
9000: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
9010: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
9020: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
9030: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
9040: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
9050: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
9060: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
9070: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
9080: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
9090: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
90a0: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
90b0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
90c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
90d0: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
90e0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
90f0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
9100: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
9110: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
9120: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
9130: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
9140: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
9150: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9160: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
9170: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
9180: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9190: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
91a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
91b0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
91c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
91d0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
91e0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
91f0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
9200: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
9210: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
9220: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
9230: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
9240: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
9250: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
9260: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
9270: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
9280: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
9290: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
92a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
92b0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
92c0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
92d0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
92e0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
92f0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
9300: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
9310: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
9320: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
9330: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
9340: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
9350: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
9360: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9370: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9380: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
9390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
93a0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
93b0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
93c0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
93d0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
93e0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
93f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9400: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
9410: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
9420: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
9430: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
9440: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
9450: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
9460: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
9470: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
9480: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
9490: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
94a0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
94b0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
94c0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
94d0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
94e0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
94f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9500: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9510: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9520: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9530: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
9540: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9550: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
9560: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
9570: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
9580: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
9590: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
95a0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
95b0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
95c0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
95d0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
95e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
95f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9600: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9610: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9620: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
9630: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
9640: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
9650: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
9660: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
9670: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
9680: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
9690: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
96a0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
96b0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
96c0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
96d0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
96e0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
96f0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
9700: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9710: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9720: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9730: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9740: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9750: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9760: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9770: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9780: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9790: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
97a0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
97b0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
97c0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
97d0: 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f  ee also [SQLITE_
97e0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
97f0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
9800: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9810: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9820: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9830: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9840: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9850: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9860: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9870: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9880: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9890: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
98a0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69  journal file (ei
98b0: 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c  ther.** the [rol
98c0: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f  lback journal] o
98d0: 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65  r the [write-ahe
98e0: 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70  ad log]) for a p
98f0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9900: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9910: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9920: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9930: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
9940: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9950: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9960: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e  .** No longer in
9970: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e   use..**.** <li>
9980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9990: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  YNC]].** The [SQ
99a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
99b0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
99c0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
99d0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a  by SQLite and.**
99e0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
99f0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
9a00: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65  ore the xSync me
9a10: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
9a20: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65  on a.** database
9a30: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
9a40: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79  . Or, if the xSy
9a50: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74  nc method is not
9a60: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63   invoked .** bec
9a70: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61  ause the user ha
9a80: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c  s configured SQL
9a90: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52  ite with .** [PR
9aa0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9ab0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
9ac0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73  onous=OFF] it is
9ad0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63   invoked in plac
9ae0: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79  e .** of the xSy
9af0: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f  nc method. In mo
9b00: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f  st cases, the po
9b10: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70  inter argument p
9b20: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  assed with.** th
9b30: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
9b40: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72  is NULL. However
9b50: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  , if the databas
9b60: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20  e file is being 
9b70: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72  synced.** as par
9b80: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74  t of a multi-dat
9b90: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68  abase commit, th
9ba0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  e argument point
9bb0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  s to a nul-termi
9bc0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
9bd0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74  containing the t
9be0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74  ransactions mast
9bf0: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  er-journal file 
9c00: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74  name. VFSes that
9c10: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64   .** do not need
9c20: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f   this signal sho
9c30: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9c40: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9c50: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a   Applications .*
9c60: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  * should not cal
9c70: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9c80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9c90: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9ca0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20  oing so may .** 
9cb0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
9cc0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9cd0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9ce0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9cf0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9d00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9d10: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a  MMIT_PHASETWO]].
9d20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9d30: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
9d40: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETWO] opcode is 
9d50: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9d60: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a  ally by SQLite.*
9d70: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68  * and sent to th
9d80: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72  e VFS after a tr
9d90: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65  ansaction has be
9da0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d  en committed imm
9db0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20  ediately.** but 
9dc0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62  before the datab
9dd0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e  ase is unlocked.
9de0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e   VFSes that do n
9df0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9e00: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69  nal.** should si
9e10: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9e20: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9e30: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
9e40: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  ot call.** [sqli
9e50: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9e60: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9e70: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9e80: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9e90: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f   .** operation o
9ea0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9eb0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9ec0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9ed0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9ee0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9ef0: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
9f00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9f10: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
9f20: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9f30: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
9f40: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
9f50: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
9f60: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
9f70: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
9f80: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
9f90: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
9fa0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
9fb0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
9fc0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
9fd0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
9fe0: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
9ff0: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
a000: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
a010: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
a020: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
a030: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
a040: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
a050: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
a060: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
a070: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
a080: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
a090: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
a0a0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
a0b0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
a0c0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
a0d0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
a0e0: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
a0f0: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
a100: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
a110: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
a120: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
a130: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
a140: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
a150: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
a160: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
a170: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a180: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
a190: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
a1a0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
a1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a1c0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
a1d0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
a1e0: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
a1f0: 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74  r is the new ret
a200: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
a210: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
a220: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
a230: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
a240: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
a250: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
a260: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
a270: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
a280: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
a290: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
a2a0: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
a2b0: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
a2c0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
a2d0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
a2e0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
a2f0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
a300: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
a310: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
a320: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a330: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a340: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
a350: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a360: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
a370: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a380: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a390: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
a3a0: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
a3b0: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
a3c0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
a3d0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
a3e0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
a3f0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a400: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
a410: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
a420: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
a430: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
a440: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
a450: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
a460: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
a470: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
a480: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a490: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
a4a0: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
a4b0: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
a4c0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
a4d0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
a4e0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
a4f0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
a500: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
a510: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
a520: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
a530: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
a540: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
a550: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
a560: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
a570: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
a580: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
a590: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
a5a0: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
a5b0: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
a5c0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
a5d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a5e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a5f0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a600: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a610: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a620: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a630: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a640: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a650: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a660: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a670: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a680: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a690: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a6a0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a6b0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a6c0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a6d0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a6e0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a6f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a700: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a710: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a730: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a740: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a750: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a760: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a770: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a780: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a790: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a7a0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a7b0: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a7c0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a7d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a7e0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a7f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a800: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a810: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a820: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a830: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a840: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a850: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a860: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a870: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a880: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a890: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a8a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a8b0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a8c0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a8d0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a8e0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a8f0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a900: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
a910: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
a920: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a940: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a950: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
a960: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a970: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
a980: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
a990: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
a9a0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
a9b0: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
a9c0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
a9d0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
a9e0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
a9f0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
aa00: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
aa10: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
aa20: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
aa30: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
aa40: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
aa50: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
aa60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aa70: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
aa80: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
aa90: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
aaa0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
aab0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
aac0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
aad0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
aae0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
aaf0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
ab00: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
ab10: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
ab20: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
ab30: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
ab40: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
ab50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ab60: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
ab70: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
ab80: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
ab90: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
aba0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
abb0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
abc0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
abd0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
abe0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
abf0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
ac00: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
ac10: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
ac20: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
ac30: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
ac40: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
ac50: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
ac60: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
ac70: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
ac80: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
ac90: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
aca0: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
acb0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
acc0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
acd0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
ace0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
acf0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
ad00: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
ad10: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
ad20: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
ad30: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ad40: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
ad50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad60: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ad70: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
ad80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
ad90: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
ada0: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
adb0: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
adc0: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
add0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
ade0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
adf0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
ae00: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
ae10: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
ae20: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
ae30: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
ae40: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
ae50: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
ae60: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
ae70: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
ae80: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
ae90: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
aea0: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
aeb0: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
aec0: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
aed0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
aee0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
aef0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
af00: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
af10: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
af20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
af30: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
af40: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
af50: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
af60: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
af70: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
af80: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
af90: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
afa0: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
afb0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
afc0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
afd0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
afe0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
aff0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
b000: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
b010: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
b020: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
b030: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
b040: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
b050: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
b060: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
b070: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
b080: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
b090: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
b0a0: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
b0b0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
b0c0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
b0d0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
b0e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b0f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b100: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
b110: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
b120: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
b130: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
b140: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
b150: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
b160: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b170: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
b180: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
b190: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
b1a0: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
b1b0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
b1c0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
b1d0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
b1e0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
b1f0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
b200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b210: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b220: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b230: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
b240: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
b250: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
b260: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
b270: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b280: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b290: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b2a0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
b2b0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
b2c0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
b2d0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
b2e0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
b2f0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
b300: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
b310: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
b320: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
b330: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
b340: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
b350: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
b360: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
b370: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
b380: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
b390: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
b3a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b3b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b3c0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
b3d0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
b3e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
b3f0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
b400: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
b410: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
b420: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
b430: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
b440: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
b450: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
b460: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
b470: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
b480: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
b490: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b4a0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
b4b0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
b4c0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
b4d0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
b4e0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
b4f0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
b500: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
b510: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
b520: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
b530: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b540: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b550: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b560: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b570: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
b580: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
b590: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
b5a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b5b0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
b5c0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
b5d0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
b5e0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
b5f0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
b600: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
b610: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
b620: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
b630: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
b640: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
b650: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
b660: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
b670: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
b680: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
b690: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
b6a0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
b6b0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
b6c0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
b6d0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
b6e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
b6f0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b700: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b710: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b720: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b730: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b740: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b750: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b760: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b770: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b780: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b790: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b7a0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b7b0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b7c0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b7d0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b7e0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b7f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b800: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b810: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b820: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b830: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b840: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b850: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b860: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b870: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b880: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b890: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b8a0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b8b0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b8c0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b8d0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b8e0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b8f0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b900: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
b910: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
b920: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
b930: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
b940: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
b950: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
b960: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
b970: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
b980: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
b990: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
b9a0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
b9b0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
b9c0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
b9d0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
b9e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b9f0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
ba00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
ba10: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
ba20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
ba30: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
ba40: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
ba50: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
ba60: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
ba70: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
ba80: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
ba90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
baa0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
bab0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
bac0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
bad0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
bae0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
baf0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
bb00: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
bb10: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
bb20: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
bb30: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
bb40: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
bb50: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
bb60: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
bb70: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
bb80: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
bb90: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
bba0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
bbb0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
bbc0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
bbd0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
bbe0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
bbf0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
bc00: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
bc10: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
bc20: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
bc30: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
bc40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bc50: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
bc60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc70: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
bc80: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
bc90: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
bca0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
bcb0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
bcc0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
bcd0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
bce0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
bcf0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
bd00: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
bd10: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
bd20: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
bd30: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bd40: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
bd50: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
bd60: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
bd70: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
bd80: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
bd90: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
bda0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
bdb0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
bdc0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
bdd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
bde0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
bdf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
be10: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
be30: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
be40: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
be50: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
be60: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
be70: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
be80: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
be90: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
bea0: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
beb0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
bec0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
bed0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
bee0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
bef0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
bf00: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
bf10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bf20: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
bf30: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
bf40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bf50: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_GET_HANDLE] op
bf60: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
bf70: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a   to obtain the.*
bf80: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74  * underlying nat
bf90: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bfa0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
bfb0: 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20  a file handle.  
bfc0: 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e  This file.** con
bfd0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
bfe0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
bff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
c000: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c010: 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20  e and.** writes 
c020: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61  the resulting va
c030: 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  lue there..**.**
c040: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c050: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
c060: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
c070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c080: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
c090: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
c0a0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
c0b0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
c0c0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
c0d0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
c0e0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
c0f0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
c100: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
c110: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
c120: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
c130: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
c140: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
c150: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
c160: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
c170: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
c180: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
c190: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c1a0: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
c1b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c1c0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
c1d0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
c1e0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
c1f0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
c200: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
c210: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
c220: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
c230: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
c240: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
c250: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
c260: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
c270: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
c280: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
c290: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
c2a0: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
c2b0: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
c2c0: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
c2d0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
c2e0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
c2f0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
c300: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
c310: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c320: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
c330: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c340: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
c350: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c360: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
c370: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
c380: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c390: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c3a0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
c3b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c3c0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
c3d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c3e0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
c3f0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c400: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
c410: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
c420: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
c430: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
c440: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
c450: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c460: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
c470: 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ode.  .**.** <li
c480: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c490: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
c4a0: 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b  TE]].** If the [
c4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c4c0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c4d0: 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20   opcode returns 
c4e0: 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a  SQLITE_OK, then.
c4f0: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
c500: 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64  riptor is placed
c510: 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65   in "batch write
c520: 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a   mode", which.**
c530: 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65   means all subse
c540: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
c550: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64  ations will be d
c560: 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65  eferred and done
c570: 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61  .** atomically a
c580: 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49  t the next [SQLI
c590: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c5a0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20  ATOMIC_WRITE].  
c5b0: 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20  Systems.** that 
c5c0: 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62  do not support b
c5d0: 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74  atch atomic writ
c5e0: 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  es will return S
c5f0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a  QLITE_NOTFOUND..
c600: 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  ** ^Following a 
c610: 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54  successful SQLIT
c620: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
c630: 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70  OMIC_WRITE and p
c640: 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63  rior to.** the c
c650: 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  losing [SQLITE_F
c660: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
c670: 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20  IC_WRITE] or.** 
c680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
c690: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
c6a0: 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c  ITE], SQLite wil
c6b0: 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53  l make.** no VFS
c6c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73   interface calls
c6d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71   on the same [sq
c6e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65  lite3_file] file
c6f0: 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65   descriptor.** e
c700: 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20  xcept for calls 
c710: 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65  to the xWrite me
c720: 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69  thod and the xFi
c730: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c740: 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45  .** with [SQLITE
c750: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
c760: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
c770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c780: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c790: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c7a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c7b0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f  OMIC_WRITE] opco
c7c0: 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72  de causes all wr
c7d0: 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  ite.** operation
c7e0: 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76  s since the prev
c7f0: 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20  ious successful 
c800: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c  call to .** [SQL
c810: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c820: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f  ATOMIC_WRITE] to
c830: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74   be performed at
c840: 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69  omically..** Thi
c850: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  s file control r
c860: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
c870: 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  K] if and only i
c880: 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72  f the writes wer
c890: 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d  e.** all perform
c8a0: 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
c8b0: 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f  and have been co
c8c0: 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69  mmitted to persi
c8d0: 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a  stent storage..*
c8e0: 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
c8f0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
c900: 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  it is successful
c910: 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  , this file cont
c920: 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65  rol takes.** the
c930: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
c940: 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72   out of batch wr
c950: 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74  ite mode so that
c960: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
c970: 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  ** write operati
c980: 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64  ons are independ
c990: 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ent..** ^SQLite 
c9a0: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
c9b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
c9c0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9d0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
c9e0: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
c9f0: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
ca00: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
ca10: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
ca20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ca30: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
ca40: 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20  OMIC_WRITE]].** 
ca50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ca60: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
ca70: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
ca80: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
ca90: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
caa0: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
cab0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
cac0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
cad0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cae0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
caf0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
cb00: 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74   ^This file cont
cb10: 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69  rol takes the fi
cb20: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
cb30: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
cb40: 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74   mode.** so that
cb50: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
cb60: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
cb70: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
cb80: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
cb90: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
cba0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cbb0: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
cbc0: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
cbd0: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
cbe0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cbf0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cc00: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f  IC_WRITE]..** </
cc10: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
cc20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
cc30: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
cc40: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
cc60: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
cc70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
cc80: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
cc90: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
cca0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
ccb0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
ccc0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
ccd0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
cce0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
ccf0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
cd00: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
cd10: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
cd20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
cd30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cd40: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
cd50: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
cd60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cd70: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
cd80: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
cd90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cda0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
cdb0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
cdc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cdd0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
cde0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
cdf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ce00: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
ce10: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
ce20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce30: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
ce40: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
ce50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ce60: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
ce70: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
ce80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
ce90: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
cea0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
ceb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
cec0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
ced0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
cee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
cef0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
cf00: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
cf10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
cf20: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
cf30: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
cf40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
cf50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cf60: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
cf70: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
cf80: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
cf90: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
cfa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
cfb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cfc0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
cfd0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
cfe0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
cff0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
d000: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
d010: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
d020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d030: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
d040: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
d050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d060: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
d070: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
d080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d090: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20  NTL_RBU         
d0a0: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64             26.#d
d0b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d0c0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20  TL_VFS_POINTER  
d0d0: 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65            27.#de
d0e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d0f0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
d100: 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66  R        28.#def
d110: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d120: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
d130: 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69  E       29.#defi
d140: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d150: 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20  PDB             
d160: 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e         30.#defin
d170: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
d180: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
d190: 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65  E     31.#define
d1a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
d1b0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
d1c0: 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
d1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
d1e0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
d1f0: 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65  TE  33../* depre
d200: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
d210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
d220: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d230: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
d240: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
d250: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
d260: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
d270: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
d280: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
d290: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
d2a0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
d2b0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
d2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
d2d0: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
d2e0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
d2f0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
d300: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
d310: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
d320: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
d330: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
d340: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
d350: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
d360: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
d370: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
d380: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
d390: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
d3a0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
d3b0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
d3c0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
d3d0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
d3e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
d3f0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
d400: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
d410: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
d420: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
d430: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
d440: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
d450: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
d460: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
d470: 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  oadable Extensio
d480: 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20  n Thunk.**.** A 
d490: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f  pointer to the o
d4a0: 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70  paque sqlite3_ap
d4b0: 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63  i_routines struc
d4c0: 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61  ture is passed a
d4d0: 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  s.** the third p
d4e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72  arameter to entr
d4f0: 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61  y points of [loa
d500: 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
d510: 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75  ].  This.** stru
d520: 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79  cture must be ty
d530: 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72  pedefed in order
d540: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
d550: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
d560: 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61  s.** on some pla
d570: 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64  tforms..*/.typed
d580: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
d590: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
d5a0: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
d5b0: 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nes;../*.** CAPI
d5c0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
d5d0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
d5e0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
d5f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
d600: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
d610: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
d620: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
d630: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
d640: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
d650: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
d660: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
d670: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
d680: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
d690: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
d6a0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
d6b0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
d6c0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
d6d0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
d6e0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
d6f0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
d700: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
d710: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
d720: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
d730: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
d740: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
d750: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
d760: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
d770: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
d780: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
d790: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
d7a0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
d7b0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
d7c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
d7d0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
d7e0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
d7f0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
d800: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
d810: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
d820: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
d830: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
d840: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
d850: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
d860: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
d870: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
d880: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
d890: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
d8a0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
d8b0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
d8c0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
d8d0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
d8e0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
d8f0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
d900: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
d910: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
d920: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
d930: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
d940: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
d950: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
d960: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
d970: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
d980: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
d990: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
d9a0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
d9b0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
d9c0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
d9d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
d9e0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
d9f0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
da00: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
da10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
da20: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
da30: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
da40: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
da50: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
da60: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
da70: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
da80: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
da90: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
daa0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
dab0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
dac0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
dad0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
dae0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
daf0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
db00: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
db10: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
db20: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
db30: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
db40: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
db50: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
db60: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
db70: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
db80: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
db90: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
dba0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
dbb0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
dbc0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
dbd0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
dbe0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
dbf0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
dc00: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
dc10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
dc20: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
dc30: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
dc40: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
dc50: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
dc60: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
dc70: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
dc80: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
dc90: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
dca0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
dcb0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
dcc0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
dcd0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
dce0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
dcf0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
dd00: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
dd10: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
dd20: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
dd30: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
dd40: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
dd50: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
dd60: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
dd70: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
dd80: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
dd90: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
dda0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
ddb0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
ddc0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
ddd0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
dde0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
ddf0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
de00: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
de10: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
de20: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
de30: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
de40: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
de50: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
de60: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
de70: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
de80: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
de90: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
dea0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
deb0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
dec0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
ded0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
dee0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
def0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
df00: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
df10: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
df20: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
df30: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
df40: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
df50: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
df60: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
df70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
df80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
df90: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
dfa0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
dfb0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
dfc0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
dfd0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
dfe0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
dff0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
e000: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
e010: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
e020: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
e030: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
e040: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
e050: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e060: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
e070: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
e080: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
e090: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
e0a0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
e0b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
e0c0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
e0d0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
e0e0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
e0f0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
e100: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
e110: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
e120: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
e130: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
e140: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
e150: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
e160: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
e170: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e180: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
e190: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e1a0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
e1b0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e1c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
e1d0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
e1e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
e1f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
e210: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
e220: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e230: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
e240: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e250: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
e260: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e270: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
e280: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
e290: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
e2a0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
e2b0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
e2c0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
e2d0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
e2e0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
e2f0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
e300: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
e310: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
e320: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
e330: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
e340: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
e350: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
e360: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
e370: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
e380: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
e390: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
e3a0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
e3b0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
e3c0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
e3d0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
e3e0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
e3f0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
e400: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
e410: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
e420: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
e430: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
e440: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
e450: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
e460: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
e470: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
e480: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
e490: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
e4a0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
e4b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
e4c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
e4d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
e4e0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
e4f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
e500: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
e510: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
e520: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
e530: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
e540: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
e550: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e560: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
e570: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
e580: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
e590: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
e5a0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
e5b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e5c0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
e5d0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
e5e0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
e5f0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
e600: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
e610: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
e620: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
e630: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
e640: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
e650: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
e660: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
e670: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
e680: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
e690: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
e6a0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
e6b0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
e6c0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
e6d0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
e6e0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
e6f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
e700: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
e710: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
e720: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
e730: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
e740: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
e750: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
e760: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
e770: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
e780: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
e790: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
e7a0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
e7b0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
e7c0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
e7d0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
e7e0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
e7f0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
e800: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
e810: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
e820: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
e830: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
e840: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
e850: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
e860: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
e870: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
e880: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
e890: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
e8a0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
e8b0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
e8c0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
e8d0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
e8e0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
e8f0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
e900: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
e910: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
e920: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
e930: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
e940: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
e950: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
e960: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
e970: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
e980: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
e990: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
e9a0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
e9b0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
e9c0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
e9d0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
e9e0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
e9f0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
ea00: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
ea10: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
ea20: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
ea30: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
ea40: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
ea50: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
ea60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
ea70: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
ea80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ea90: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
eaa0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
eab0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
eac0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ead0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
eae0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
eaf0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
eb00: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
eb10: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
eb20: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
eb30: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
eb40: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
eb50: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
eb60: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
eb70: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
eb80: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
eb90: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
eba0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
ebb0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
ebc0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
ebd0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
ebe0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
ebf0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
ec00: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
ec10: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
ec20: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
ec30: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
ec40: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
ec50: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
ec60: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
ec70: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
ec80: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
ec90: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
eca0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
ecb0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
ecc0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
ecd0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
ece0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
ecf0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
ed00: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
ed10: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
ed20: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
ed30: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
ed40: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
ed50: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
ed60: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
ed70: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
ed80: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
ed90: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
eda0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
edb0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
edc0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
edd0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
ede0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
edf0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
ee00: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
ee10: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
ee20: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
ee30: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
ee40: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
ee50: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
ee60: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
ee70: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
ee80: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
ee90: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
eea0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
eeb0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
eec0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
eed0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
eee0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
eef0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
ef00: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
ef10: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
ef20: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
ef30: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
ef40: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
ef50: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
ef60: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
ef70: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
ef80: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
ef90: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
efa0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
efb0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
efc0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
efd0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
efe0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
eff0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
f000: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
f010: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
f020: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
f030: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
f040: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
f050: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
f060: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
f070: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
f080: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
f090: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
f0a0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
f0b0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
f0c0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
f0d0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
f0e0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
f0f0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
f100: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
f110: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
f120: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
f130: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
f140: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
f150: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
f160: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
f170: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
f180: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
f190: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
f1a0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
f1b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
f1c0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
f1d0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
f1e0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
f1f0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
f200: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
f210: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
f220: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
f230: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
f240: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
f250: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
f260: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
f270: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
f280: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
f290: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
f2a0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
f2b0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
f2c0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
f2d0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
f2e0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
f2f0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
f300: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
f310: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
f320: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
f330: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
f340: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f350: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
f360: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
f370: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
f380: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
f390: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
f3a0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
f3b0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
f3c0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
f3d0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
f3e0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
f3f0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
f400: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
f410: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
f420: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
f430: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
f440: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
f450: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
f460: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
f470: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
f480: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
f490: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
f4a0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
f4b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
f4c0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
f4d0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
f4e0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
f4f0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
f500: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
f510: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
f520: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
f530: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
f540: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
f550: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
f560: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
f570: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
f580: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
f590: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
f5a0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
f5b0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
f5c0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
f5d0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
f5e0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
f5f0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
f600: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
f610: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
f620: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
f630: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
f640: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
f650: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
f660: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
f670: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
f680: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
f690: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
f6a0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
f6b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
f6c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
f6d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f6e0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
f6f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
f700: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
f710: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f720: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
f730: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
f740: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
f750: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
f760: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f770: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
f780: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
f790: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
f7a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f7b0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
f7c0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
f7d0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
f7e0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
f7f0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
f800: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
f810: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
f820: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
f830: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
f840: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
f850: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
f860: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
f870: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
f880: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
f890: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
f8a0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
f8b0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
f8c0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
f8d0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
f8e0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
f8f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
f900: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
f910: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
f920: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
f930: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
f940: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
f950: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
f960: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
f970: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f980: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
f990: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
f9a0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
f9b0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
f9c0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
f9d0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
f9e0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
f9f0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
fa00: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
fa10: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
fa20: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
fa30: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
fa40: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
fa50: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
fa60: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
fa70: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
fa80: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
fa90: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
faa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fab0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fac0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
fad0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
fae0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
faf0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
fb00: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fb10: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
fb20: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
fb30: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
fb40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fb50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
fb60: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
fb70: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
fb80: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
fb90: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
fba0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
fbb0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
fbc0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
fbd0: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
fbe0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
fbf0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
fc00: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
fc10: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
fc20: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
fc30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fc40: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
fc50: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
fc60: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
fc70: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
fc80: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
fc90: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
fca0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
fcb0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
fcc0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
fcd0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
fce0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
fcf0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
fd00: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
fd10: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
fd20: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
fd30: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
fd40: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
fd50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
fd60: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
fd70: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
fd80: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
fd90: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
fda0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
fdb0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
fdc0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
fdd0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
fde0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
fdf0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
fe00: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
fe10: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
fe20: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
fe30: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
fe40: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
fe50: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
fe60: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
fe70: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
fe80: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
fe90: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
fea0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
feb0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
fec0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
fed0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
fee0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
fef0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
ff00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ff10: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
ff20: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ff30: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ff40: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
ff50: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ff60: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
ff70: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
ff80: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
ff90: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
ffa0: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
ffb0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
ffc0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
ffd0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ffe0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
fff0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10000 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
10010 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
10020 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10030 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
10040 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10050 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
10060 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
10070 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
10080 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
10090 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
100a0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
100b0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
100c0 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
100d0 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
100e0 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
100f0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10100 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
10110 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
10120 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
10130 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
10140 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
10150 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
10160 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
10170 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
10180 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
10190 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
101a0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
101b0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
101c0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
101d0 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
101e0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
101f0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10200 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
10210 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10220 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10230 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
10240 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
10250 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
10260 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
10270 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
10280 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
10290 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
102a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
102b0 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
102c0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
102d0 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
102e0 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
102f0 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
10300 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
10310 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
10320 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
10330 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
10340 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
10350 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
10360 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
10370 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
10380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10390 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
103a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
103b0 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
103c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
103d0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
103e0 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
103f0 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
10400 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
10410 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
10420 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
10430 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
10440 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
10450 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
10460 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
10470 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
10480 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
10490 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
104a0 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
104b0 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
104c0 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
104d0 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
104e0 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
104f0 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
10500 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
10510 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
10520 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
10530 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
10550 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
10560 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
10570 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
10580 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
10590 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
105a0 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
105b0 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
105c0 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
105d0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
105e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
105f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10600 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
10610 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
10620 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10630 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
10640 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
10650 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
10660 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
10670 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
10680 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
10690 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
106a0 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
106b0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
106c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
106d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
106e0 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
106f0 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
10700 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
10710 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10720 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
10730 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
10740 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
10750 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
10760 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
10770 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10780 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
10790 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
107a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
107b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
107c0 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
107d0 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
107e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
107f0 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
10800 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
10810 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
10820 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
10830 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
10840 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10850 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
10860 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
10870 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
10880 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
10890 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
108a0 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
108b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108c0 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
108d0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
108e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
10900 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
10910 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
10920 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
10930 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10940 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
10950 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
10960 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10970 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
10980 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
10990 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
109a0 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
109b0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
109c0 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
109d0 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
109e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
109f0 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
10a00 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
10a10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10a20 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
10a30 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
10a40 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
10a50 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
10a60 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
10a70 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
10a80 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10a90 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
10aa0 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
10ab0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10ac0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
10ad0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10ae0 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
10af0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10b00 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
10b10 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10b20 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
10b30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10b40 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
10b50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
10b60 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
10b70 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
10b80 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
10b90 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
10ba0 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
10bb0 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
10bc0 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
10bd0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
10be0 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
10bf0 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
10c00 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
10c10 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
10c20 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
10c30 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
10c40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10c50 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10c60 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
10c70 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
10c80 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
10c90 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
10ca0 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
10cb0 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
10cc0 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
10cd0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
10ce0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
10cf0 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
10d00 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
10d10 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
10d20 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10d30 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
10d40 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
10d50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
10d60 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
10d70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10d80 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
10d90 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
10da0 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
10db0 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
10dc0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
10dd0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
10de0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
10df0 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
10e00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
10e10 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
10e20 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
10e30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
10e40 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
10e50 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
10e60 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
10e70 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10e80 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
10e90 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
10ea0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10eb0 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
10ec0 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
10ed0 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
10ee0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
10ef0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
10f00 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10f10 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
10f20 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
10f30 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10f40 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10f50 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
10f60 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
10f70 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
10f80 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
10f90 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
10fa0 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
10fb0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
10fc0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
10fd0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
10fe0 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
10ff0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
11000 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
11010 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
11020 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
11030 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11040 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
11050 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
11060 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
11070 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11080 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11090 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
110a0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
110b0 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
110c0 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
110d0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
110e0 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
110f0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
11100 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
11110 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
11120 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
11130 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
11140 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
11150 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
11160 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
11170 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
11180 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
11190 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
111a0 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
111b0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
111c0 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
111d0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
111e0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
111f0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
11200 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
11210 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11220 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
11230 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
11240 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11250 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
11260 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
11270 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
11280 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11290 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
112a0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
112b0 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
112c0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
112d0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
112e0 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
112f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11300 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
11310 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11320 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
11330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
11340 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
11350 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
11360 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
11370 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
11380 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
11390 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
113a0 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
113b0 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
113c0 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
113d0 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
113e0 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
113f0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
11400 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
11410 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
11420 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
11430 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
11440 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
11450 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
11460 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11470 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
11480 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
11490 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
114a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
114b0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
114c0 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
114d0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
114e0 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
114f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
11500 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
11510 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
11520 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
11530 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
11540 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
11550 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
11560 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
11570 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11580 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
11590 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
115a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
115b0 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
115c0 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
115d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
115e0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
115f0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11600 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
11610 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
11620 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
11630 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
11640 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
11650 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
11660 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
11670 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
11680 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
11690 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
116a0 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
116b0 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
116c0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
116d0 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
116e0 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
116f0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
11700 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
11710 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
11720 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
11730 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
11740 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11750 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
11760 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
11770 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
11780 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
11790 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
117a0 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
117b0 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
117c0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
117d0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
117e0 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
117f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11800 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
11810 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
11820 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
11830 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
11840 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
11850 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
11860 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
11870 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
11880 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11890 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
118a0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
118b0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
118c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
118d0 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
118e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
118f0 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
11900 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
11910 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
11920 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
11930 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11940 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
11950 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
11960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
11970 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
11980 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
11990 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
119a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
119b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
119c0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
119d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
119e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
119f0 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
11a00 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
11a10 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
11a20 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
11a30 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
11a40 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
11a50 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
11a60 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
11a70 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
11a80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11a90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
11aa0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11ab0 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
11ac0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
11ad0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
11ae0 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
11af0 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
11b00 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
11b10 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
11b20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
11b30 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
11b40 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
11b50 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
11b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
11b70 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
11b80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11b90 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
11ba0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
11bb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
11bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11bd0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
11be0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
11bf0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
11c00 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
11c10 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
11c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11c30 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
11c40 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
11c50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11c60 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
11c70 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
11c80 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
11c90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ca0 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
11cb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11cc0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
11cd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11ce0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
11cf0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
11d00 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
11d10 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11d20 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
11d30 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
11d40 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
11d50 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
11d60 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
11d70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
11d80 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
11d90 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
11da0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
11db0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
11dc0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
11dd0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
11de0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
11df0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11e00 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
11e10 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
11e20 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
11e30 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
11e40 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
11e50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11e60 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
11e70 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
11e80 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
11e90 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
11ea0 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
11eb0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
11ec0 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
11ed0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
11ee0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
11ef0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
11f00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11f10 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11f20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
11f30 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
11f40 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
11f50 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11f60 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
11f70 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11f80 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
11f90 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11fa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11fb0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
11fc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11fd0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
11fe0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
11ff0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12000 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
12010 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
12020 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
12030 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
12040 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
12050 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
12060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12070 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
12080 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
12090 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
120a0 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
120b0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
120c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
120d0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
120e0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
120f0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
12100 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
12110 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
12120 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
12130 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
12140 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
12150 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
12160 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
12170 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
12180 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
12190 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
121a0 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
121b0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
121c0 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
121d0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
121e0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
121f0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
12200 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
12210 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
12220 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
12230 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
12240 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
12250 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
12260 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
12270 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
12280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12290 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
122a0 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
122b0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
122c0 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
122d0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
122e0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
122f0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
12300 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
12310 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
12320 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
12330 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
12340 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
12350 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
12360 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
12370 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
12380 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
12390 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
123a0 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
123b0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
123c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
123d0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
123e0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
123f0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
12400 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
12410 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
12420 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
12430 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
12440 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
12450 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
12460 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
12470 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
12480 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
12490 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
124a0 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
124b0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
124c0 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
124d0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
124e0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
124f0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
12500 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
12510 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12520 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
12530 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
12540 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
12550 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
12560 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
12570 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12580 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
12590 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
125a0 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
125b0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
125c0 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
125d0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
125e0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
125f0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
12600 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
12610 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
12620 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
12630 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
12640 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
12650 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12660 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
12670 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
12680 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
12690 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
126a0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
126b0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
126c0 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
126d0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
126e0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
126f0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12700 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
12710 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
12720 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
12730 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
12740 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
12750 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
12760 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
12770 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
12780 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
12790 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
127a0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
127b0 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
127c0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
127d0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
127e0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
127f0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
12800 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
12810 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
12820 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
12830 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
12840 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
12850 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
12860 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
12870 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
12880 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
12890 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
128a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
128b0 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
128c0 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
128d0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
128e0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
128f0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
12900 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
12910 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
12920 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
12930 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
12940 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
12950 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
12960 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
12970 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
12980 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
12990 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
129a0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
129b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
129c0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
129d0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
129e0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
129f0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
12a00 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
12a10 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
12a20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
12a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12a40 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
12a50 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
12a60 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
12a70 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
12a80 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
12a90 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
12aa0 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
12ab0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
12ac0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
12ad0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
12ae0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
12af0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
12b00 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
12b10 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
12b20 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
12b30 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
12b40 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
12b50 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
12b60 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
12b70 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
12b80 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
12b90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
12ba0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
12bb0 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
12bc0 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
12bd0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
12be0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
12bf0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
12c00 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
12c10 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
12c20 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
12c30 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
12c40 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
12c50 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
12c60 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
12c70 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12c80 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
12c90 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
12ca0 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
12cb0 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
12cc0 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
12cd0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
12ce0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
12cf0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
12d00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12d10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
12d20 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
12d30 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
12d40 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12d50 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12d60 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
12d70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
12d80 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
12d90 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
12da0 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
12db0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
12dc0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
12dd0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
12de0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12df0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
12e00 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
12e10 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
12e20 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
12e30 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
12e40 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
12e50 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
12e60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
12e70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12e80 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
12e90 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
12ea0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
12eb0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
12ec0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
12ed0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
12ee0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
12ef0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
12f00 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
12f10 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
12f20 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
12f30 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
12f40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
12f50 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
12f60 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
12f70 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
12f80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12f90 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
12fa0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
12fb0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12fc0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
12fd0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
12fe0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
12ff0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
13000 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
13010 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
13020 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13030 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13050 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
13060 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13070 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13080 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
13090 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
130a0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
130b0 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
130c0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
130d0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
130e0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
130f0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
13100 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
13110 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
13120 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
13130 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
13140 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13150 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13160 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13170 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13180 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13190 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
131a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
131b0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
131c0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
131d0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
131e0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
131f0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
13200 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
13210 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13220 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
13230 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13240 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
13250 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13260 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
13270 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13280 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13290 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
132a0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
132b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
132c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
132d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
132e0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
132f0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13300 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13310 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13320 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13330 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
13340 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13350 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
13360 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
13370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13380 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
13390 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
133a0 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
133b0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
133c0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
133d0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
133e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
133f0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
13400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13410 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
13420 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
13430 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
13440 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
13450 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
13460 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
13470 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
13480 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
13490 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
134a0 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
134b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
134c0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
134d0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
134e0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
134f0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13500 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13510 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13520 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
13530 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
13540 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
13550 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
13560 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
13570 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
13580 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
13590 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
135a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
135b0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
135c0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
135d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
135e0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
135f0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13600 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13610 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
13620 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13630 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
13640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13650 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13660 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13670 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13680 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13690 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
136a0 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
136b0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
136c0 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
136d0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
136e0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
136f0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
13700 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
13710 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
13720 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13730 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13740 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
13750 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
13760 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
13770 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13780 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
13790 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
137a0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
137b0 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
137c0 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
137d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
137e0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
137f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
13800 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
13810 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
13820 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
13830 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
13840 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
13850 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
13860 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
13870 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
13880 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
13890 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
138a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
138b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
138c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
138d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
138e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
138f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
13900 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
13910 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
13920 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
13930 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13940 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13950 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13960 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13970 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
13980 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
13990 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
139a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
139b0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
139c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
139d0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
139e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
139f0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
13a00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13a10 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
13a20 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13a30 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13a40 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
13a50 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13a60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13a70 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13a80 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
13a90 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
13aa0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
13ab0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
13ac0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13ad0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
13ae0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
13af0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13b00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
13b10 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
13b20 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
13b30 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
13b40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
13b50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
13b60 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13b70 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
13b80 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
13b90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13ba0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
13bb0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13bc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13bd0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13be0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
13bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13c00 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13c10 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
13c20 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13c30 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13c40 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
13c50 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13c70 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13c80 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
13c90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13ca0 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
13cb0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
13cc0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
13cd0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
13ce0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13cf0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13d00 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
13d10 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
13d20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
13d30 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
13d40 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
13d50 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
13d60 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
13d70 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
13d80 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
13d90 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
13da0 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
13db0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13dc0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
13dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13de0 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
13df0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
13e00 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13e10 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f  G_SMALL_MALLOC o
13e20 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13e30 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a  le argument of.*
13e40 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  * type int, inte
13e50 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
13e60 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66 20 74  lean, which if t
13e70 72 75 65 20 70 72 6f 76 69 64 65 73 20 61 20 68  rue provides a h
13e80 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  int to.** SQLite
13e90 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20   that it should 
13ea0 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f  avoid large memo
13eb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69  ry allocations i
13ec0 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53  f possible..** S
13ed0 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e 20 66  QLite will run f
13ee0 61 73 74 65 72 20 69 66 20 69 74 20 69 73 20 66  aster if it is f
13ef0 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67  ree to make larg
13f00 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13f10 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d  ions,.** but som
13f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
13f30 67 68 74 20 70 72 65 66 65 72 20 74 6f 20 72 75  ght prefer to ru
13f40 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78 63 68  n slower in exch
13f50 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72  ange for.** guar
13f60 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d 65 6d  antees about mem
13f70 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  ory fragmentatio
13f80 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73 73 69  n that are possi
13f90 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20  ble if large.** 
13fa0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20  allocations are 
13fb0 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73 20 68  avoided.  This h
13fc0 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  int is normally 
13fd0 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  off..** </dd>.**
13fe0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ff0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
14000 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14010 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
14020 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14040 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
14050 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
14060 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
14070 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
14080 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
14090 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
140a0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
140b0 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
140c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
140d0 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
140e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
140f0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
14100 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
14110 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
14120 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
14130 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
14140 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
14150 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
14160 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
14170 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
14180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
14190 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
141a0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
141b0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
141c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
141d0 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
141e0 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
141f0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
14200 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14210 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
14220 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
14230 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
14240 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
14250 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
14260 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
14270 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
14280 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14290 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
142a0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
142b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
142c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
142d0 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
142e0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
142f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
14300 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14310 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69 73 20  RATCH option is 
14320 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a  no longer used..
14330 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14340 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14350 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
14360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14370 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
14380 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14390 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
143a0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
143b0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
143c0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
143d0 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
143e0 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
143f0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
14400 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
14410 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14420 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
14430 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14440 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
14450 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
14460 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
14470 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14480 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
14490 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
144a0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
144b0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
144c0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
144d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
144e0 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
144f0 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
14500 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
14510 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
14520 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
14530 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
14540 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
14550 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
14560 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
14570 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
14580 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
14590 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
145a0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
145b0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
145c0 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
145d0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
145e0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
145f0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
14600 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
14610 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
14620 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
14630 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
14640 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
14650 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14660 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
14670 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
14680 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
14690 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
146a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
146b0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
146c0 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
146d0 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
146e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
146f0 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
14700 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
14710 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
14720 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
14730 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
14740 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
14750 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
14760 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
14770 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
14780 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
14790 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
147a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
147b0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
147c0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
147d0 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
147e0 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
147f0 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
14800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14810 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
14820 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
14830 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
14840 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
14850 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
14860 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
14870 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
14880 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
14890 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
148a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
148b0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
148c0 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
148d0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
148e0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
148f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
14900 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
14910 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
14920 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
14930 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
14940 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
14950 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
14960 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
14970 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
14980 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
14990 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
149a0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
149b0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
149c0 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
149d0 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
149e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
149f0 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14a00 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14a10 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14a30 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14a40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14a50 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
14a60 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14a70 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14a80 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14a90 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14aa0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
14ab0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14ac0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14ad0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14ae0 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14af0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14b00 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14b10 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14b20 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  HE]..** ^The SQL
14b30 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
14b40 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14b50 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
14b60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  te is compiled.*
14b70 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53  * with either [S
14b80 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14b90 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45  SYS3] or [SQLITE
14ba0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
14bb0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
14bc0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
14bd0 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77  f invoked otherw
14be0 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ise..** ^There a
14bf0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
14c00 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
14c10 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20  FIG_HEAP:.** An 
14c20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
14c30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
14c40 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
14c50 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
14c60 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
14c70 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
14c80 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14c90 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
14ca0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
14cb0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
14cc0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
14cd0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
14ce0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
14cf0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
14d00 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
14d10 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
14d20 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
14d30 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
14d40 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
14d50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14d60 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
14d70 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
14d80 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
14d90 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
14da0 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
14db0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
14dc0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
14dd0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
14de0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14df0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
14e00 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
14e10 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
14e20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
14e30 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
14e40 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
14e50 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
14e60 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
14e70 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
14e80 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
14e90 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
14ea0 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
14eb0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
14ec0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
14ed0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14ee0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
14ef0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
14f00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14f10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
14f20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f30 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
14f40 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14f50 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70  _CONFIG_MUTEX op
14f60 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14f70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14f80 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  ch is a.** point
14f90 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14fa0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14fb0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14fc0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
14fd0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
14fe0 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76  ifies alternativ
14ff0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
15000 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
15010 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63   used.** in plac
15020 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  e the mutex rout
15030 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
15040 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
15050 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15060 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
15070 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
15080 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
15090 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
150a0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
150b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
150c0 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
150d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
150e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
150f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15100 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15110 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15120 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15130 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
15140 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
15150 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
15160 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
15170 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
15180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
15190 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
151a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
151b0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
151c0 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
151d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
151e0 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
151f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15200 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
15210 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15220 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
15230 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15240 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15250 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
15260 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15270 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
15280 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15290 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
152a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
152b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
152c0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
152d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
152e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
152f0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
15300 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15310 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
15320 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
15330 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
15340 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
15350 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
15360 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
15370 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
15380 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
15390 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
153a0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
153b0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
153c0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
153d0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
153e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
153f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15400 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15410 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15420 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15430 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15440 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15450 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15460 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15470 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15480 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15490 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
154a0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
154b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
154c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
154d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
154e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
154f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
15500 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15510 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
15520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15530 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
15540 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
15550 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15560 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  E option takes t
15570 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
15580 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74  t determine.** t
15590 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20  he default size 
155a0 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
155b0 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74  ory on each [dat
155c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
155d0 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  ]..** The first 
155e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
155f0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15600 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15610 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
15620 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
15630 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
15640 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
15650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15660 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54  tion.)^  ^(SQLIT
15670 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15680 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c  DE.** sets the <
15690 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
156a0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
156b0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
156c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
156d0 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69   option to [sqli
156e0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
156f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15700 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
15710 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
15720 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
15730 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
15740 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15750 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15760 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
15770 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15780 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
15790 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
157a0 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
157b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
157c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
157d0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
157e0 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
157f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15800 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
15810 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
15820 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63  .** the interfac
15830 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  e to a custom pa
15840 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
15850 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53  ntation.)^.** ^S
15860 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
15870 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
15880 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15890 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e  s2] object.</dd>
158a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
158b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
158c0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
158d0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
158e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
158f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15900 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74  G_GETPCACHE2 opt
15910 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15920 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15930 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15940 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
15950 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15960 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
15970 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74  e copies of.** t
15980 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20  he current page 
15990 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
159a0 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
159b0 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
159c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
159d0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
159e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
159f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
15a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a10 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
15a20 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
15a30 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
15a40 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
15a50 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
15a60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15a70 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
15a80 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
15a90 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
15aa0 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
15ab0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
15ac0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
15ad0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
15ae0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
15af0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
15b00 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
15b10 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
15b20 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
15b30 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
15b40 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
15b50 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
15b60 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
15b70 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15b80 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
15b90 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
15ba0 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
15bb0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
15bc0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
15bd0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
15be0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
15bf0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
15c00 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
15c10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
15c20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
15c30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15c40 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
15c50 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
15c60 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
15c70 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
15c80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15c90 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
15ca0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
15cb0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
15cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
15cd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
15ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
15cf0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
15d00 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
15d10 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
15d20 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
15d30 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
15d40 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
15d50 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
15d60 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
15d70 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
15d80 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
15d90 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
15da0 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
15db0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
15dc0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
15dd0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
15de0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
15df0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
15e00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
15e10 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
15e20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
15e30 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
15e40 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
15e50 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
15e60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
15e70 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
15e80 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
15e90 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
15ea0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15eb0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
15ec0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
15ed0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
15ee0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69  _CONFIG_URI opti
15ef0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15f00 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
15f10 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f  pe int..** If no
15f20 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  n-zero, then URI
15f30 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15f40 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
15f50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15f60 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  is zero,.** then
15f70 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15f80 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
15f90 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61  ed.)^ ^If URI ha
15fa0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15fb0 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61  ly.** enabled, a
15fc0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73  ll filenames pas
15fd0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
15fe0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
15ff0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a  3_open_v2()],.**
16000 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
16010 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
16020 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
16030 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
16040 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
16050 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
16060 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
16070 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
16080 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
16090 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
160a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
160b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
160c0 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
160d0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
160e0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
160f0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
16100 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
16110 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
16120 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
16130 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
16140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16150 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
16160 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
16170 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16180 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
16190 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
161a0 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
161b0 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
161c0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
161d0 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
161e0 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
161f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16200 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
16210 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
16220 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16230 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
16240 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16250 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16260 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74  G_INDEX_SCAN opt
16270 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16280 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72  le integer.** ar
16290 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
162a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
162b0 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
162c0 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
162d0 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73  isable.** the us
162e0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
162f0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
16300 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
16310 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
16320 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  r..** ^The defau
16330 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
16340 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
16350 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
16360 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16370 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
16380 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
16390 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
163a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
163b0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
163c0 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
163d0 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
163e0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
163f0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
16400 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
16410 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
16420 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
16430 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
16440 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
16450 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
16460 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
16470 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
16480 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
16490 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
164a0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
164b0 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
164c0 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
164d0 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
164e0 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
164f0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
16500 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
16510 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
16520 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16530 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
16540 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16550 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
16560 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
16570 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
16580 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
16590 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
165a0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
165b0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
165c0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
165d0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
165e0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
165f0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
16600 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
16610 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
16620 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16630 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
16640 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16650 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
16660 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
16670 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
16680 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
16690 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
166a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
166b0 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
166c0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
166d0 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
166e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
166f0 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
16700 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
16710 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
16720 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
16730 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
16740 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
16750 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
16760 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
16770 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16780 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
16790 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
167a0 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
167b0 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
167c0 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
167d0 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
167e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
167f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
16800 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
16810 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
16820 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
16830 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16840 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
16850 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
16860 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
16870 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
16880 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
16890 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
168a0 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
168b0 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
168c0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
168d0 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
168e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
168f0 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
16900 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
16910 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
16920 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
16930 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
16940 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
16950 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
16960 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
16970 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16980 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16990 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
169a0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
169b0 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
169c0 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
169d0 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
169e0 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
169f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16a00 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
16a10 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
16a20 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
16a30 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
16a40 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
16a50 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
16a60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16a70 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16a80 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16a90 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16aa0 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
16ab0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16ac0 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
16ad0 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
16ae0 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
16af0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
16b00 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
16b10 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
16b20 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
16b30 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
16b40 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
16b50 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
16b60 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
16b70 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
16b80 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
16b90 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
16ba0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
16bb0 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
16bc0 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
16bd0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
16be0 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
16bf0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
16c00 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
16c10 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
16c20 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
16c30 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
16c40 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  ize.** will be s
16c50 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
16c60 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73  d if necessary s
16c70 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  o that it does n
16c80 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ot exceed the.**
16c90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61   compile-time ma
16ca0 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20  ximum mmap size 
16cb0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
16cc0 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53  QLITE_MAX_MMAP_S
16cd0 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  IZE] compile-tim
16ce0 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  e option.)^.** ^
16cf0 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65  If either argume
16d00 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  nt to this optio
16d10 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  n is negative, t
16d20 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e  hen that argumen
16d30 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20  t is.** changed 
16d40 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74  to its compile-t
16d50 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a  ime default..**.
16d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16d70 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16d80 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
16d90 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16da0 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  EAPSIZE.** <dd>^
16db0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16dc0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16dd0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
16de0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
16df0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
16e00 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77  ed for Windows w
16e10 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
16e20 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72  WIN32_MALLOC] pr
16e30 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
16e40 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53  o.** defined. ^S
16e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16e60 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65  32_HEAPSIZE take
16e70 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  s a 32-bit unsig
16e80 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ned integer valu
16e90 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66  e.** that specif
16ea0 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ies the maximum 
16eb0 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61  size of the crea
16ec0 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20  ted heap..**.** 
16ed0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16ee0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a  PCACHE_HDRSZ]].*
16ef0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16f00 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16f10 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16f20 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16f30 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74  E_HDRSZ option t
16f40 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
16f50 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
16f60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16f70 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
16f80 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74  writes into that
16f90 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d   integer the num
16fa0 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20  ber of extra.** 
16fb0 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72  bytes per page r
16fc0 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68  equired for each
16fd0 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45   page in [SQLITE
16fe0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16ff0 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e  E]..** The amoun
17000 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65  t of extra space
17010 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68   required can ch
17020 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f  ange depending o
17030 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a  n the compiler,.
17040 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f  ** target platfo
17050 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76  rm, and SQLite v
17060 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  ersion..**.** [[
17070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17080 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ASZ]].** <dt>SQL
17090 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
170a0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
170b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
170c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
170d0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
170e0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20   which.** is an 
170f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
17100 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d   and sets the "M
17110 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22  inimum PMA Size"
17120 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68   for the multith
17130 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72  readed.** sorter
17140 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72   to that integer
17150 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d  .  The default m
17160 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20  inimum PMA Size 
17170 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  is set by the.**
17180 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f   [SQLITE_SORTER_
17190 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74  PMASZ] compile-t
171a0 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77  ime option.  New
171b0 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75   threads are lau
171c0 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70  nched.** to help
171d0 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61   with sort opera
171e0 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69  tions when multi
171f0 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67  threaded sorting
17200 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28  .** is enabled (
17210 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  using the [PRAGM
17220 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61  A threads] comma
17230 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75  nd) and the amou
17240 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a  nt of content.**
17250 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78   to be sorted ex
17260 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73  ceeds the page s
17270 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69  ize times the mi
17280 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20  nimum of the.** 
17290 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69  [PRAGMA cache_si
172a0 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20  ze] setting and 
172b0 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  this value..**.*
172c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
172d0 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
172e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
172f0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17300 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54  _SPILL.** <dd>^T
17310 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17320 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20  _STMTJRNL_SPILL 
17330 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17340 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
17350 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73  which.** becomes
17360 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20   the [statement 
17370 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74  journal] spill-t
17380 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64  o-disk threshold
17390 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e  .  .** [Statemen
173a0 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20  t journals] are 
173b0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75  held in memory u
173c0 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20  ntil their size 
173d0 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78  (in bytes).** ex
173e0 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73  ceeds this thres
173f0 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70  hold, at which p
17400 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72  oint they are wr
17410 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a  itten to disk..*
17420 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65  * Or if the thre
17430 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61  shold is -1, sta
17440 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
17450 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a  are always held.
17460 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69  ** exclusively i
17470 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e  n memory..** Sin
17480 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e  ce many statemen
17490 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72  t journals never
174a0 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73   become large, s
174b0 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c  etting the spill
174c0 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f  .** threshold to
174d0 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73   a value such as
174e0 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74   64KiB can great
174f0 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d  ly reduce the am
17500 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72  ount of.** I/O r
17510 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f  equired to suppo
17520 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c  rt statement rol
17530 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65  lback..** The de
17540 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
17550 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
17560 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68  controlled by th
17570 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d  e.** [SQLITE_STM
17580 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d  TJRNL_SPILL] com
17590 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
175a0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
175b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
175c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
175d0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
175e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
175f0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
17600 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
17610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17620 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
17630 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
17640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17650 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
17660 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
17670 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
17680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17690 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
176a0 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
176b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
176c0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
176d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
176e0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 4e  CH       6  /* N
176f0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
17700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17710 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
17720 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
17730 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
17740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17750 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
17760 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
17770 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
17780 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
17790 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
177a0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
177b0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
177c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
177d0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
177e0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
177f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
17800 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17810 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
17820 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
17830 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17840 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
17850 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
17860 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
17870 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
17880 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
17890 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
178b0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
178c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
178d0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
178e0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
178f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17900 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17910 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
17920 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
17930 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
17940 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
17950 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
17960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17970 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
17980 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
17990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
179a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
179b0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
179c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
179d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
179e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
179f0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
17a00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17a10 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
17a20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17a30 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
17a40 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
17a50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a60 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
17a70 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
17a80 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
17a90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17aa0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
17ab0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
17ac0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
17ad0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
17ae0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17af0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
17b00 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
17b10 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
17b20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17b30 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
17b40 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
17b50 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
17b60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17b80 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
17b90 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
17ba0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17bb0 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17bc0 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
17bd0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
17be0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17bf0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20  SMALL_MALLOC    
17c00 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65      27  /* boole
17c10 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  an */../*.** CAP
17c20 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
17c30 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
17c40 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
17c50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
17c60 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
17c70 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
17c80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17c90 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
17ca0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
17cb0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17cc0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
17cd0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17ce0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
17cf0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
17d00 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
17d10 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
17d20 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
17d30 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
17d40 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
17d50 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
17d60 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
17d70 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
17d80 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
17d90 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
17da0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
17db0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
17dc0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
17dd0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
17de0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
17df0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
17e00 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
17e10 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
17e20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
17e30 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
17e40 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
17e50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17e60 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
17e70 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
17e80 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17e90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
17ea0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17eb0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
17ec0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
17ed0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
17ee0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
17ef0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17f00 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
17f10 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
17f20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
17f30 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
17f40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17f50 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
17f60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
17f70 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
17f80 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
17f90 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
17fa0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
17fb0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
17fc0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17fd0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
17fe0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17ff0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
18000 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
18010 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
18020 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
18030 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
18040 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
18050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
18060 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
18070 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
18080 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
18090 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
180a0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
180b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
180c0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
180d0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
180e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
180f0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
18100 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
18110 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
18120 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
18130 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
18140 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
18150 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
18160 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
18170 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
18180 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
18190 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
181a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
181b0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
181c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
181d0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
181e0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
181f0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
18200 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
18210 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
18220 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
18230 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
18240 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
18250 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
18260 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
18270 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
18280 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
18290 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
182a0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
182b0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
182c0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
182d0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
182e0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
182f0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
18300 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
18310 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
18320 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
18330 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
18340 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
18350 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
18360 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
18370 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
18380 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
18390 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
183a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
183b0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
183c0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
183d0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
183e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
183f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18400 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
18410 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18420 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18430 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18440 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
18450 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
18460 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
18470 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
18480 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18490 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
184a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
184b0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
184c0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
184d0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
184e0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
184f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
18500 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
18510 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18520 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
18530 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
18540 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18550 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18560 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18570 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18580 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18590 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
185a0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
185b0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
185c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
185d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
185e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
185f0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18600 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
18610 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
18620 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
18630 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18640 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18650 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18660 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
18670 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
18680 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18690 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
186a0 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
186b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
186c0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
186d0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
186e0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
186f0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18700 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18710 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18720 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
18730 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
18740 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
18750 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
18760 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
18770 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
18780 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18790 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
187a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
187b0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
187c0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
187d0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
187e0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
187f0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
18800 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18810 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18820 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18830 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18840 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18850 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18860 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
18870 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18880 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18890 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
188a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
188b0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
188c0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
188d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
188e0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
188f0 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f   disable the two
18900 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72  -argument.** ver
18910 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73  sion of the [fts
18920 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66  3_tokenizer()] f
18930 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73  unction which is
18940 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
18950 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74  [FTS3] full-text
18960 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65   search engine e
18970 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65  xtension..** The
18980 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
18990 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
189a0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
189b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
189c0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
189d0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
189e0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
189f0 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ) or.** positive
18a00 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f   to enable fts3_
18a10 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e  tokenizer() or n
18a20 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
18a30 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
18a40 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18a50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18a60 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18a70 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18a80 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18a90 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18aa0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18ab0 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  r fts3_tokenizer
18ac0 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
18ad0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
18ae0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18af0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18b00 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18b10 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18b20 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18b30 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
18b40 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18b50 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
18b60 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18b70 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
18b80 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
18b90 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18ba0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18bb0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18bc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
18bd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
18be0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
18bf0 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
18c00 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
18c10 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
18c20 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
18c30 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
18c40 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
18c50 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
18c60 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
18c70 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
18c80 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18c90 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18ca0 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
18cb0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
18cc0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
18cd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
18ce0 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
18cf0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18d00 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
18d10 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
18d20 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
18d30 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
18d40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18d50 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
18d60 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
18d70 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18d80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18d90 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
18da0 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
18db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
18dc0 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
18dd0 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
18de0 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
18df0 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
18e00 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
18e10 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
18e20 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
18e30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18e40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18e50 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18e60 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18e70 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18e80 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18e90 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18ea0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18eb0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
18ec0 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
18ed0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
18ee0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18ef0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18f00 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
18f10 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
18f20 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
18f30 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18f40 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18f50 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
18f60 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18f70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
18f80 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
18f90 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18fa0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
18fb0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
18fc0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
18fd0 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
18fe0 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
18ff0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
19000 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
19010 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
19020 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
19030 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
19040 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
19050 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
19060 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
19070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
19080 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
19090 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
190a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
190b0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
190c0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
190d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
190e0 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
190f0 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
19100 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
19110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19120 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
19130 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19140 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
19150 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c  O_CKPT_ON_CLOSE<
19160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75  /dt>.** <dd> Usu
19170 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74  ally, when a dat
19180 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64  abase in wal mod
19190 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64  e is closed or d
191a0 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a  etached from a .
191b0 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
191c0 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b  le, SQLite check
191d0 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d  s if this will m
191e0 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61  ean that there a
191f0 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f  re now no .** co
19200 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c  nnections at all
19210 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
19220 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66  . If so, it perf
19230 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e  orms a checkpoin
19240 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  t .** operation 
19250 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74  before closing t
19260 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54  he connection. T
19270 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  his option may b
19280 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65  e used to.** ove
19290 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76  rride this behav
192a0 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20  iour. The first 
192b0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
192c0 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69   to this operati
192d0 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  on.** is an inte
192e0 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74  ger - non-zero t
192f0 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70  o disable checkp
19300 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20  oints-on-close, 
19310 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20  or zero (the.** 
19320 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62  default) to enab
19330 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63  le them. The sec
19340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19350 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19360 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f   integer.** into
19370 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65   which is writte
19380 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19390 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65  cate whether che
193a0 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
193b0 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64  e.** have been d
193c0 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74  isabled - 0 if t
193d0 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61  hey are not disa
193e0 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20  bled, 1 if they 
193f0 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  are..** </dd>.**
19400 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19410 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51  BCONFIG_ENABLE_Q
19420 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PSG</dt>.** <dd>
19430 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43  ^(The SQLITE_DBC
19440 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
19450 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74  G option activat
19460 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65  es or deactivate
19470 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20  s.** the [query 
19480 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74  planner stabilit
19490 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50  y guarantee] (QP
194a0 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51  SG).  When the Q
194b0 50 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a  PSG is active,.*
194c0 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71  * a single SQL q
194d0 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77  uery statement w
194e0 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74  ill always use t
194f0 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
19500 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  m regardless.** 
19510 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f  of values of [bo
19520 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e  und parameters].
19530 29 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61  )^ The QPSG disa
19540 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20  bles some query 
19550 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a  optimizations.**
19560 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68   that look at th
19570 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e  e values of boun
19580 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68  d parameters, wh
19590 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d  ich can make som
195a0 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f  e queries.** slo
195b0 77 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50  wer.  But the QP
195c0 53 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e  SG has the advan
195d0 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65  tage of more pre
195e0 64 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f  dictable behavio
195f0 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20  r.  With.** the 
19600 51 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c  QPSG active, SQL
19610 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
19620 75 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65  use the same que
19630 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66  ry plan in the f
19640 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75  ield as.** was u
19650 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
19660 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a  ng in the lab..*
19670 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  * </dd>.**.** </
19680 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
19690 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
196a0 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20  AINDBNAME       
196b0 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e       1000 /* con
196c0 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66  st char* */.#def
196d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
196e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
196f0 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
19700 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
19710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19720 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19730 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
19740 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
19750 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19760 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19770 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
19780 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
19790 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
197a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
197b0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
197c0 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
197d0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
197e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
197f0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
19800 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
19810 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19820 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19830 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
19840 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a  OSE      1006 /*
19850 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19860 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19870 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
19880 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20             1007 
19890 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
198a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
198b0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
198c0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
198d0 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
198e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
198f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
19900 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
19910 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
19920 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
19930 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
19940 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
19950 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
19960 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
19970 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
19980 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
19990 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
199a0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
199b0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
199c0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
199d0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
199e0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
199f0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
19a00 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
19a10 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
19a20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19a30 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
19a40 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
19a50 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
19a60 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19a70 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
19a80 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
19a90 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
19aa0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
19ab0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
19ac0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
19ad0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
19ae0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
19af0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
19b00 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
19b10 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
19b20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
19b30 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
19b40 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
19b50 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
19b60 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
19b70 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
19b80 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
19b90 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
19ba0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
19bb0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
19bc0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
19bd0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
19be0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19bf0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
19c00 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
19c10 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
19c20 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
19c30 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
19c40 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
19c50 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
19c60 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
19c70 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
19c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
19c90 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
19ca0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19cb0 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
19cc0 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
19cd0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
19ce0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
19cf0 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
19d00 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
19d10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19d20 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
19d30 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19d40 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
19d50 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
19d60 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
19d70 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
19d80 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
19d90 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
19da0 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
19db0 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
19dc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19dd0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
19de0 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
19df0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
19e00 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
19e10 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
19e20 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
19e30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
19e40 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
19e50 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19e60 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
19e70 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
19e80 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
19e90 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
19ea0 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
19eb0 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
19ec0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
19ed0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
19ee0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
19ef0 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
19f00 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
19f10 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
19f20 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
19f30 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
19f40 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
19f50 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
19f60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19f70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
19f80 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
19f90 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
19fa0 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
19fb0 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
19fc0 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
19fd0 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
19fe0 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
19ff0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1a000 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a010 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1a020 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1a030 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1a040 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1a050 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1a060 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1a070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a080 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1a090 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1a0a0 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1a0b0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1a0c0 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1a0d0 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1a0e0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1a0f0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1a100 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1a110 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1a120 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1a130 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1a140 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1a150 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1a160 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1a170 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1a180 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1a190 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1a1a0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1a1b0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1a1c0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1a1d0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1a1e0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1a1f0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1a200 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1a210 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1a220 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1a230 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1a240 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1a250 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1a260 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1a270 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1a280 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1a290 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1a2a0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1a2b0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1a2c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1a2d0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1a2e0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1a2f0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1a300 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1a310 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1a320 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1a330 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1a340 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1a350 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1a360 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1a370 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1a380 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1a390 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1a3a0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1a3b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1a3c0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1a3d0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1a3e0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1a3f0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1a400 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1a410 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1a420 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1a430 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1a440 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1a450 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1a460 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1a470 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1a480 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1a490 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1a4a0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1a4b0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1a4c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1a4d0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1a4e0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a4f0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1a500 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1a510 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1a520 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1a530 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1a540 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a550 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1a560 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a570 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1a580 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1a590 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1a5a0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1a5b0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1a5c0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1a5d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1a5e0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a5f0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1a600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a610 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1a620 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1a630 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1a640 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1a650 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1a660 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1a670 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1a680 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1a690 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1a6a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a6b0 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1a6c0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a6d0 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1a6e0 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1a6f0 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1a700 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1a710 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1a720 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a730 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1a740 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1a750 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1a760 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1a770 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a780 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a790 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a7a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a7b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a7c0 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1a7d0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a7e0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1a7f0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1a800 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a810 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1a820 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1a830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a840 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1a850 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1a860 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1a870 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1a880 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1a890 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1a8a0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1a8b0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1a8c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1a8d0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1a8e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1a8f0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a900 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a910 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1a920 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1a930 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1a940 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1a950 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1a960 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1a970 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1a980 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a990 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1a9a0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a9b0 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1a9c0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1a9d0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1a9e0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1a9f0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1aa00 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1aa10 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1aa20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1aa30 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1aa40 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1aa50 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1aa60 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1aa70 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1aa80 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1aa90 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1aaa0 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1aab0 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1aac0 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1aad0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1aae0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1aaf0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1ab00 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1ab10 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1ab20 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1ab30 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1ab40 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1ab50 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1ab60 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1ab70 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1ab80 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1ab90 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1aba0 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1abb0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1abc0 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1abd0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1abe0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1abf0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1ac00 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1ac10 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1ac20 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1ac30 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1ac40 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1ac50 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1ac60 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1ac70 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1ac80 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1ac90 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1aca0 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1acb0 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1acc0 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1acd0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1ace0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1acf0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1ad00 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1ad10 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1ad20 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1ad30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ad40 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1ad50 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1ad60 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1ad70 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1ad80 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1ad90 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1ada0 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1adb0 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1adc0 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1add0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ade0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1adf0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1ae00 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1ae10 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1ae20 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1ae30 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1ae40 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1ae50 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1ae60 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1ae70 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1ae80 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1ae90 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1aea0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1aeb0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1aec0 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1aed0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1aee0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1aef0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1af00 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1af10 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1af20 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1af30 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1af40 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1af50 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1af60 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1af70 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1af80 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1af90 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1afa0 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1afb0 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1afc0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1afd0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1afe0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1aff0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1b000 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1b010 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b020 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b030 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b040 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b050 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1b060 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1b070 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1b080 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1b090 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1b0a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1b0b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1b0c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1b0d0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1b0e0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1b0f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1b100 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1b110 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1b120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b130 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1b140 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b150 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1b160 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1b170 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1b180 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1b190 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b1a0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1b1b0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1b1c0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1b1d0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1b1e0 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1b1f0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1b200 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1b210 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1b220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b230 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1b240 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1b250 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1b260 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1b270 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1b280 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1b290 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1b2a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1b2b0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1b2c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b2d0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1b2e0 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1b2f0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1b300 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1b310 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1b320 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1b330 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1b340 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1b350 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1b360 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1b370 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1b380 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1b390 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1b3a0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1b3b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1b3c0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1b3d0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
1b3e0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1b3f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1b400 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1b410 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1b420 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1b430 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
1b440 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1b450 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1b460 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1b470 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1b480 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1b490 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1b4a0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
1b4b0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
1b4c0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1b4d0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1b4e0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
1b4f0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1b500 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
1b510 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b520 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1b530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b540 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1b550 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1b560 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b570 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b580 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1b590 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1b5a0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1b5b0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1b5c0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1b5d0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1b5e0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1b5f0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1b600 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1b610 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1b620 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1b630 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1b640 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1b650 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1b660 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1b670 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1b680 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1b690 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1b6a0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1b6b0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1b6c0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1b6d0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1b6e0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1b6f0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1b700 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1b710 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1b720 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1b730 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b740 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1b750 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1b760 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1b770 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1b780 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1b790 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1b7a0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1b7b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1b7c0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1b7d0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1b7e0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1b7f0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1b800 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1b810 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1b820 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1b830 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1b840 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1b850 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1b860 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1b870 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1b880 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1b890 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1b8a0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1b8b0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1b8c0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1b8d0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1b8e0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b8f0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1b900 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1b910 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1b920 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1b930 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1b940 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1b950 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1b960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b970 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1b980 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1b990 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1b9a0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1b9b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b9c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1b9d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1b9e0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1b9f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1ba00 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1ba10 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1ba20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ba30 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1ba40 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1ba50 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1ba60 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1ba70 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1ba80 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1ba90 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1baa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1bab0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1bac0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1bad0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1bae0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1baf0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1bb00 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1bb10 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1bb20 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1bb30 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1bb40 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1bb50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1bb60 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1bb70 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1bb80 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1bb90 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1bba0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1bbb0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1bbc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1bbd0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1bbe0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1bbf0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1bc00 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1bc10 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1bc20 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1bc30 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1bc40 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1bc50 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1bc60 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1bc70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bc80 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1bc90 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1bca0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1bcb0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1bcc0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1bcd0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1bce0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1bcf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bd00 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1bd10 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1bd20 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1bd30 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1bd40 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1bd50 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1bd60 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bd70 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1bd80 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1bd90 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1bda0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1bdb0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1bdc0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1bdd0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1bde0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1bdf0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1be00 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1be10 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1be20 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1be30 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1be40 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1be50 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1be60 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1be70 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1be80 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1be90 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1bea0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1beb0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1bec0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1bed0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1bee0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1bef0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1bf00 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1bf10 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1bf20 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1bf30 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1bf40 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1bf50 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1bf60 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1bf70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1bf80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bf90 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1bfa0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1bfb0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1bfc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1bfd0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1bfe0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1bff0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1c000 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1c010 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1c020 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1c030 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1c040 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1c050 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1c060 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1c070 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1c080 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1c090 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1c0a0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1c0b0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1c0c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c0d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1c0e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1c0f0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1c100 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1c110 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1c120 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1c130 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1c140 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1c150 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1c160 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c170 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1c180 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1c190 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1c1a0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1c1b0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1c1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1c1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1c1e0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1c1f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c200 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1c210 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1c220 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1c230 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1c240 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c250 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1c260 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1c270 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1c280 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1c290 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1c2a0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
1c2b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c2c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1c2d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c2e0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1c2f0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1c300 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1c310 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1c320 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1c330 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1c340 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1c350 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1c370 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1c380 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1c390 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c3a0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1c3b0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1c3c0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1c3d0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1c3e0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1c3f0 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1c400 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1c410 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1c420 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c430 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1c440 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1c450 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1c460 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1c470 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1c480 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1c490 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1c4a0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1c4b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1c4c0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1c4d0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1c4e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1c4f0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1c500 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1c510 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1c520 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1c530 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1c540 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1c550 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1c560 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1c570 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1c580 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1c590 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1c5a0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1c5b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1c5c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1c5d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1c5e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1c5f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1c600 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1c610 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1c620 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c630 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1c640 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1c650 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1c660 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1c670 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1c680 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1c690 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1c6a0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1c6b0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1c6c0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1c6d0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1c6e0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1c6f0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1c700 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1c710 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1c720 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1c730 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1c740 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1c750 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1c760 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1c770 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1c780 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1c790 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1c7a0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1c7b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1c7c0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1c7d0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1c7e0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1c7f0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1c800 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1c810 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1c820 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1c830 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1c840 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1c850 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1c860 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1c870 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1c880 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1c890 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1c8a0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1c8b0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1c8c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1c8d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1c8e0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1c8f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1c900 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1c910 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1c920 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1c930 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1c940 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1c950 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1c960 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1c970 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c980 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1c990 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1c9a0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1c9b0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1c9c0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1c9d0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1c9e0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1c9f0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1ca00 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1ca10 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1ca20 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1ca30 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1ca40 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1ca50 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1ca60 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1ca70 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1ca80 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1ca90 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1caa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1cab0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1cac0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1cad0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1cae0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1caf0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1cb00 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1cb10 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1cb20 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1cb30 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1cb40 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1cb50 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1cb60 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1cb70 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1cb80 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1cb90 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1cba0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1cbb0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1cbc0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1cbd0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1cbe0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1cbf0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1cc00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1cc10 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1cc20 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1cc30 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1cc40 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1cc50 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1cc60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1cc70 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1cc80 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1cc90 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1cca0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1ccb0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1ccc0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1ccd0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1cce0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1ccf0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1cd00 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1cd10 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1cd20 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1cd30 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1cd40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cd50 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1cd60 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1cd70 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1cd80 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1cd90 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1cda0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1cdb0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1cdc0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1cdd0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1cde0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1cdf0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1ce00 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1ce10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1ce20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ce30 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1ce40 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1ce50 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1ce60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ce70 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29  (sqlite3*,int(*)
1ce80 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64  (void*,int),void
1ce90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cea0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1ceb0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1cec0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ced0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1cee0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1cef0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1cf00 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1cf10 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1cf20 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1cf30 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1cf40 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1cf50 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1cf60 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1cf70 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1cf80 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1cf90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1cfa0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1cfb0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1cfc0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1cfd0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1cfe0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1cff0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1d000 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1d010 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1d020 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1d030 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1d040 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1d050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1d060 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1d070 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1d080 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1d090 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1d0a0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1d0b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1d0c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1d0d0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1d0e0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d100 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1d110 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1d120 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d130 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1d140 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1d150 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d160 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d170 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d180 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d190 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d1a0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1d1b0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1d1c0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d1d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1d1e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1d1f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1d200 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d210 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1d220 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1d230 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1d240 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d250 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1d260 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1d270 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1d280 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1d290 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1d2a0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1d2b0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1d2c0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1d2d0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1d2e0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1d2f0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1d300 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1d310 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1d320 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d330 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1d340 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1d350 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1d360 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1d370 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1d380 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1d390 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1d3a0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1d3b0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1d3c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1d3d0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1d3e0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1d3f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1d400 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1d410 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1d420 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1d430 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1d440 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1d450 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1d460 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d470 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1d480 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1d490 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1d4a0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1d4b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1d4c0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1d4d0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1d4e0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1d4f0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1d500 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1d510 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1d520 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1d530 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1d540 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1d550 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1d560 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1d570 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1d580 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1d590 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1d5a0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1d5b0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1d5c0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1d5d0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1d5e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1d5f0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1d600 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1d610 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1d620 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1d630 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1d640 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1d650 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1d660 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1d670 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1d680 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1d690 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1d6a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1d6b0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1d6c0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1d6d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1d6e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1d6f0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1d700 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1d710 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1d720 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1d730 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1d740 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1d750 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1d760 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d770 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1d780 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1d790 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1d7a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1d7b0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1d7c0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1d7d0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1d7e0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1d7f0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1d800 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d810 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1d820 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1d830 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1d840 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1d850 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1d860 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1d870 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1d880 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1d890 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1d8a0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1d8b0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1d8c0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1d8d0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1d8e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d8f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1d900 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1d910 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1d920 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d930 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1d940 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d950 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1d960 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d970 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1d980 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d990 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1d9a0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1d9b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1d9c0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1d9d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1d9e0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1d9f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1da00 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1da10 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1da20 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1da30 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1da40 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1da50 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1da60 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1da70 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1da80 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1da90 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1daa0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1dab0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1dac0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1dad0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1dae0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1daf0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1db00 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1db10 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1db20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1db30 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1db40 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1db50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1db60 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1db70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1db80 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1db90 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1dba0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1dbb0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1dbc0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1dbd0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1dbe0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1dbf0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1dc00 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1dc10 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1dc20 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1dc30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1dc40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1dc50 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1dc60 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1dc70 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1dc80 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1dc90 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1dca0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1dcb0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1dcc0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1dcd0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1dce0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1dcf0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1dd00 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1dd10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1dd20 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1dd30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1dd40 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1dd50 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1dd60 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1dd70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1dd80 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1dd90 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1dda0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1ddb0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1ddc0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1ddd0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1dde0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1ddf0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1de00 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1de10 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1de20 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1de30 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1de40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1de50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1de60 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1de70 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1de80 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1de90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1dea0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1deb0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1dec0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1ded0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1dee0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1def0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1df00 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1df10 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1df20 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1df30 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1df40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1df50 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1df60 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1df70 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1df80 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1df90 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1dfa0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1dfb0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1dfc0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1dfd0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1dfe0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1dff0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1e000 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1e010 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1e020 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1e030 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1e040 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1e050 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1e060 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1e070 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1e080 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1e090 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1e0a0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1e0b0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1e0c0 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1e0d0 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1e0e0 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1e0f0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1e100 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1e110 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1e120 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1e130 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1e140 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1e150 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1e160 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1e170 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1e180 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1e190 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1e1a0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1e1b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1e1c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e1d0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1e1e0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1e1f0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1e200 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1e210 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1e220 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1e230 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1e240 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1e250 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1e260 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1e270 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1e280 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1e290 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1e2a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e2b0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1e2c0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1e2d0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1e2e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1e2f0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1e300 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1e310 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1e320 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1e330 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1e340 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1e350 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1e360 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1e370 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1e380 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1e390 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1e3a0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1e3b0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1e3c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1e3d0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1e3e0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1e3f0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1e400 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1e410 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1e420 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1e430 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1e440 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1e450 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1e460 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1e470 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1e480 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1e490 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1e4a0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1e4b0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1e4c0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1e4d0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1e4e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1e4f0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1e500 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1e510 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1e520 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1e530 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1e540 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1e550 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1e560 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1e570 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1e580 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1e590 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1e5a0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1e5b0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1e5c0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1e5d0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1e5e0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1e5f0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1e600 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1e610 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1e620 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1e630 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1e640 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1e650 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1e660 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1e670 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1e680 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1e690 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1e6a0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1e6b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1e6c0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1e6d0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1e6e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1e6f0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1e700 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1e710 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1e720 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1e730 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1e740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e750 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1e760 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1e770 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1e780 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e790 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1e7a0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1e7b0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1e7c0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1e7d0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1e7e0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1e7f0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1e800 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1e810 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1e820 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1e830 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1e840 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1e850 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1e860 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1e870 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1e880 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1e890 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1e8a0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1e8b0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1e8c0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1e8d0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1e8e0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1e8f0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1e900 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1e910 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1e920 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1e930 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1e940 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1e950 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1e960 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1e970 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1e980 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1e990 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1e9a0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1e9b0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1e9c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1e9d0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1e9e0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1e9f0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1ea00 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1ea10 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ea20 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1ea30 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1ea40 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1ea50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ea60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1ea70 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1ea80 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1ea90 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1eaa0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1eab0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1eac0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1ead0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1eae0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1eaf0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1eb00 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1eb10 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1eb20 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1eb30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1eb40 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1eb50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1eb60 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1eb70 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1eb80 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1eb90 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1eba0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1ebb0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1ebc0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1ebd0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1ebe0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1ebf0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1ec00 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1ec10 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1ec20 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1ec30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1ec40 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1ec50 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1ec60 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1ec70 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1ec80 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1ec90 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1eca0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ecb0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ecc0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ecd0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ece0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ecf0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ed00 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1ed10 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1ed20 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1ed30 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1ed40 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1ed50 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1ed60 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1ed70 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1ed80 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1ed90 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1eda0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1edb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1edc0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1edd0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1ede0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1edf0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1ee00 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1ee10 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1ee20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1ee30 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1ee40 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1ee50 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1ee60 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1ee70 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1ee80 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1ee90 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1eea0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1eeb0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1eec0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1eed0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1eee0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1eef0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1ef00 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1ef10 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1ef20 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1ef30 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1ef40 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1ef50 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1ef60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ef70 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1ef80 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1ef90 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1efa0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1efb0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1efc0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1efd0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1efe0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1eff0 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1f000 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1f010 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1f020 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1f030 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1f040 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1f050 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1f060 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1f070 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1f080 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1f090 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1f0a0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1f0b0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1f0c0 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1f0d0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1f0e0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1f0f0 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1f100 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1f110 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1f120 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1f130 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1f140 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1f150 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1f160 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1f170 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1f180 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1f190 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1f1a0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1f1b0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1f1c0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1f1d0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1f1e0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1f1f0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1f200 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1f210 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1f220 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1f230 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1f240 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f250 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f260 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1f270 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f280 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f290 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1f2a0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f2b0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f2c0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f2d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f2e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f2f0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f300 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f310 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f320 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f330 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f340 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f350 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f360 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1f370 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1f380 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1f390 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1f3a0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1f3b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f3c0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1f3d0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1f3e0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1f3f0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1f400 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1f410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f420 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1f430 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1f440 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1f450 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1f460 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1f470 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1f480 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1f490 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f4a0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1f4b0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1f4c0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1f4d0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1f4e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f4f0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1f500 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1f510 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f520 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1f530 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1f540 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1f550 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1f560 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1f570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f580 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1f590 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1f5a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1f5b0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f5c0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1f5d0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1f5e0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1f5f0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1f600 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1f610 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1f620 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1f630 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1f640 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f650 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1f660 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f670 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1f680 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1f690 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1f6a0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1f6b0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1f6c0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1f6d0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1f6e0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1f6f0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1f700 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1f710 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f720 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1f730 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1f740 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1f750 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1f760 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1f770 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1f780 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1f790 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1f7a0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1f7b0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1f7c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f7d0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1f7e0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1f7f0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1f800 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1f810 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1f820 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1f830 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1f840 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1f850 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1f860 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1f870 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1f880 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f890 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1f8a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f8b0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1f8c0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1f8d0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1f8e0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1f8f0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1f900 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1f910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1f920 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f930 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f940 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1f950 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1f960 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1f970 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1f980 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f990 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1f9a0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1f9b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f9c0 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1f9d0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1f9e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1f9f0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1fa00 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1fa10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1fa20 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1fa30 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1fa40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1fa50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fa60 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1fa70 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1fa80 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1fa90 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1faa0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1fab0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1fac0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1fad0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1fae0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1faf0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1fb00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1fb10 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1fb20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1fb30 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1fb40 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1fb50 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1fb60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fb70 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1fb80 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1fb90 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1fba0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1fbb0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1fbc0 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1fbd0 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1fbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1fbf0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1fc00 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1fc10 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1fc20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1fc30 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1fc40 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1fc50 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1fc60 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1fc70 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1fc80 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1fc90 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1fca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1fcb0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1fcc0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1fcd0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1fce0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1fcf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fd00 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1fd10 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1fd20 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1fd30 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1fd40 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1fd50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1fd60 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1fd70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fd80 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1fd90 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1fda0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1fdb0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1fdc0 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1fdd0 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1fde0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1fdf0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1fe00 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1fe10 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1fe20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1fe30 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1fe40 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1fe50 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1fe60 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1fe70 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1fe80 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1fe90 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1fea0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1feb0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1fec0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1fed0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1fee0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1fef0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1ff00 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1ff10 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1ff20 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1ff30 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1ff40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1ff50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ff60 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1ff70 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1ff80 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1ff90 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1ffa0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1ffb0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1ffc0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1ffd0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1ffe0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1fff0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
20000 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
20010 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
20020 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
20030 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
20040 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
20050 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
20060 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
20070 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
20080 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
20090 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
200a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
200b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
200c0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
200d0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
200e0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
200f0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
20100 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
20110 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
20120 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
20130 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
20140 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
20150 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
20160 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
20170 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
20180 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
20190 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
201a0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
201b0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
201c0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
201d0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
201e0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
201f0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
20200 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
20210 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20220 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
20230 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
20240 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
20250 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
20260 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
20270 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
20280 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
20290 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
202a0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
202b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
202c0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
202d0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
202e0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
202f0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
20300 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
20310 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
20320 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
20330 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
20340 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
20350 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
20360 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20370 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20380 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
20390 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
203a0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
203b0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
203c0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
203d0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
203e0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
203f0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
20400 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
20410 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
20420 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
20430 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
20440 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
20450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
20460 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
20470 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
20480 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20490 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
204a0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
204b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
204c0 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
204d0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
204e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
204f0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
20500 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
20510 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
20520 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20530 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
20540 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
20550 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
20560 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
20570 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
20580 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
20590 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
205a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
205b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
205c0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
205d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
205e0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
205f0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
20600 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20610 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
20620 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
20630 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20640 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20650 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20660 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
20670 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
20680 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
20690 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
206a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
206b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
206c0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
206d0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
206e0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
206f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20700 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
20710 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20720 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
20730 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
20740 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
20750 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20760 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
20770 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20780 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
20790 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
207a0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
207b0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
207c0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
207d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
207e0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
207f0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20800 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
20810 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
20820 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
20830 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20840 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
20850 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
20860 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
20870 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
20880 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
20890 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
208a0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
208b0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
208c0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
208d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
208e0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
208f0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20900 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
20910 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20920 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
20930 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20940 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
20950 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
20960 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
20970 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
20980 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
20990 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
209a0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
209b0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
209c0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
209d0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
209e0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
209f0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
20a00 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
20a10 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20a20 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
20a30 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
20a40 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
20a50 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
20a60 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20a70 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20a80 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20a90 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20aa0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20ab0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
20ac0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
20ad0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
20ae0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
20af0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
20b00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
20b10 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20b20 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
20b30 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
20b40 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
20b50 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
20b60 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
20b70 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20b80 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20b90 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20ba0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
20bb0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
20bc0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
20bd0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
20be0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20bf0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
20c00 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
20c10 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
20c20 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
20c30 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
20c40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
20c50 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
20c60 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
20c70 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20c80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20c90 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20ca0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
20cb0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
20cc0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
20cd0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
20ce0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
20cf0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
20d00 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
20d10 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20d20 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
20d30 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
20d40 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
20d50 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
20d60 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
20d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
20d80 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20d90 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
20da0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
20db0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
20dc0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
20dd0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
20de0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
20df0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
20e00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
20e10 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f  KEYWORDS: {autho
20e20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a  rizer callback}.
20e30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20e40 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20e50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20e60 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20e70 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20e90 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20ea0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20eb0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20ec0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20ed0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
20ee0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
20ef0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
20f00 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
20f10 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20f20 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
20f30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20f40 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20f50 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
20f60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
20f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f80 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e  e16_v2()],.** an
20f90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20fa0 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74  re16_v3()].  ^At
20fb0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
20fc0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
20fd0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
20fe0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
20ff0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
21000 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
21010 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
21020 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21030 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
21040 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
21050 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
21060 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
21070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21080 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
21090 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
210a0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
210b0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
210c0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
210d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
210e0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
210f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21100 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
21110 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
21120 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
21130 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
21140 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
21150 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
21160 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
21170 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
21180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21190 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
211a0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
211b0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
211c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
211d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
211e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
211f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21200 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
21210 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
21220 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
21230 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
21240 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
21250 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
21260 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21270 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21280 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
21290 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
212a0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
212b0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
212c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
212d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
212e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
212f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
21300 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
21310 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
21320 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
21330 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
21340 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
21350 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
21360 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
21370 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
21380 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21390 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
213a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
213b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
213c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
213d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
213e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
213f0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
21400 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21410 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
21420 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21430 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
21440 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
21450 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
21460 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
21470 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21480 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
21490 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
214a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
214b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
214c0 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
214d0 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
214e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
214f0 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
21500 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
21510 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
21520 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
21530 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
21540 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
21550 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
21560 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
21570 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
21580 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
21590 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
215a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
215b0 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
215c0 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
215d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
215e0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
215f0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
21600 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21610 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
21620 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
21630 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21640 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
21650 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
21660 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
21670 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
21680 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
21690 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
216a0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
216b0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
216c0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
216d0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
216e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
216f0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
21700 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
21710 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
21720 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
21730 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
21740 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
21750 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
21760 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
21770 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
21780 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
21790 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
217a0 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
217b0 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
217c0 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
217d0 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
217e0 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
217f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
21800 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
21810 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
21820 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
21830 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
21840 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
21850 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
21860 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
21870 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
21880 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
21890 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
218a0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
218b0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
218c0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
218d0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
218e0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
218f0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21900 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
21910 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
21920 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
21930 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
21940 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
21950 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
21960 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
21970 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
21980 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
21990 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
219a0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
219b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
219c0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
219d0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
219e0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
219f0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21a00 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
21a10 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
21a20 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
21a30 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
21a40 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
21a50 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
21a60 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
21a70 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
21a80 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
21a90 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21aa0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21ab0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21ac0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21ad0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21ae0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21af0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21b00 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21b10 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21b20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21b30 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
21b40 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
21b50 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
21b60 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
21b70 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
21b80 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21b90 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
21ba0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
21bb0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21bc0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21bd0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21be0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21bf0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21c00 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21c10 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
21c20 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
21c30 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
21c40 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
21c50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
21c60 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
21c70 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
21c80 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
21c90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
21ca0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
21cb0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21cc0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21cd0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21ce0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21cf0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21d10 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21d20 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21d30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21d40 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
21d50 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
21d60 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
21d70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
21d80 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
21d90 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
21da0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
21db0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21dc0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21dd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21de0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21df0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21e00 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21e10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21e20 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21e30 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
21e40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
21e50 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
21e60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21e70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
21e80 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
21e90 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21ea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21eb0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21ec0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21ed0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21ee0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21ef0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21f00 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21f10 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21f20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21f30 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
21f40 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
21f50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
21f60 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
21f70 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
21f80 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
21f90 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
21fa0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
21fb0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
21fc0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
21fd0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21fe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21ff0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
22000 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
22010 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22020 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
22030 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
22040 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
22050 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
22060 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
22070 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
22080 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
22090 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
220a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
220b0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
220c0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
220d0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
220e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
220f0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
22100 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
22110 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
22120 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
22130 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
22140 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
22150 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
22160 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
22170 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
22180 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
22190 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
221a0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
221b0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
221c0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
221d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
221e0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
221f0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22200 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22210 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
22220 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22230 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
22240 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
22250 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
22260 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
22270 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
22280 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
22290 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
222a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
222b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
222c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
222d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
222e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
222f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
22300 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22310 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22320 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
22330 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
22340 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
22350 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
22360 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
22370 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
22380 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
22390 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
223a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
223b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
223c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
223d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
223e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
223f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
22400 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
22410 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
22420 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
22430 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
22440 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22450 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
22460 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22470 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22480 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
22490 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
224a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
224b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
224c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
224d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
224e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
224f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
22500 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22510 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
22520 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
22530 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
22540 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
22550 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
22560 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
22570 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
22580 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
22590 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
225a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
225b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
225c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
225d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
225e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
225f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
22600 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
22610 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
22620 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
22630 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
22640 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
22650 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
22660 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
22670 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
22680 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
22690 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
226a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
226b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
226c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
226d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
226e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
226f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
22700 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
22710 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
22720 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
22730 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22740 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22750 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
22760 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
22770 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
22780 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
22790 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
227a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
227b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
227c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
227d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
227e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
227f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
22800 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
22810 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22820 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
22830 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
22840 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
22850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22860 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
22870 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
22880 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22890 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
228b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
228c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
228d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
228e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
228f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22900 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
22910 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
22920 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22930 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22950 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
22960 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
22970 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22980 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22990 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
229a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
229b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
229c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
229d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
229e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
229f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22a00 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
22a10 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22a20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22a30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22a40 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
22a50 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22a60 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22a70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22a80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22a90 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
22aa0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22ab0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22ac0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ad0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
22ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
22af0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22b00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b20 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
22b30 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
22b40 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22b50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22b60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22b70 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
22b80 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
22b90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22ba0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22bc0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
22bd0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
22be0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22bf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
22c20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
22c30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22c40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22c60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
22c70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
22c80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22c90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cb0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
22cc0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
22cd0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22ce0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
22d10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
22d20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22d30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22d50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
22d60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
22d70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22d80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
22da0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
22db0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
22dc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22dd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
22df0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
22e00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
22e10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
22e20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
22e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
22e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22e50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
22e60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22e70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22e80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
22e90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22ea0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
22eb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22ec0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22ed0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
22ee0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
22ef0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22f00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22f10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22f20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
22f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
22f40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22f50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22f60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22f70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
22f80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
22f90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
22fa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22fb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22fc0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
22fd0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
22fe0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22ff0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
23000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23010 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
23020 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
23030 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
23040 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23060 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
23070 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
23080 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23090 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
230a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
230b0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
230c0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
230d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
230e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
230f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23100 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
23110 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
23120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23130 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
23140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23150 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
23160 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
23170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
23180 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
23190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
231a0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
231b0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
231c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
231d0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
231e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
231f0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
23200 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
23210 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
23220 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
23230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23240 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
23250 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
23260 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
23270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
23280 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
23290 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
232a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
232b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
232c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
232d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
232e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
232f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23300 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23310 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
23320 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
23330 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23340 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
23350 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
23360 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
23370 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
23380 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
23390 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
233a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
233b0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
233c0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
233d0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
233e0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
233f0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
23400 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
23410 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
23420 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
23430 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
23440 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
23450 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
23460 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
23470 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
23480 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
23490 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
234a0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
234b0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
234c0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
234d0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
234e0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
234f0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
23500 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
23510 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
23520 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
23530 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
23540 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
23550 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
23560 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
23570 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
23580 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
23590 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
235a0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
235b0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
235c0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
235d0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
235e0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
235f0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
23600 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
23610 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
23620 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
23630 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
23640 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
23650 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
23660 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
23670 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23680 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23690 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
236a0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
236b0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
236c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
236d0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
236e0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
236f0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23700 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
23710 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
23720 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
23730 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
23740 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
23750 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
23760 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23770 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23780 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23790 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
237a0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
237b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
237c0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
237d0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
237e0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
237f0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23800 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
23810 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
23820 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
23830 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23840 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23850 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
23860 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23870 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23880 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23890 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
238a0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
238b0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
238c0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
238d0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
238e0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
238f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23900 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
23910 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23920 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
23930 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23940 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
23950 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
23960 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23970 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
23980 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
23990 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
239a0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
239b0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
239c0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
239d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
239e0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
239f0 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
23a00 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
23a10 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
23a20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
23a30 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
23a40 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
23a50 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
23a60 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
23a70 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
23a80 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
23a90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
23aa0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
23ab0 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e  race_v2()] is an
23ac0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
23ad0 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
23ae0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
23af0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23b00 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
23b10 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
23b20 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
23b30 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
23b40 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23b50 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
23b60 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
23b70 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
23b80 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
23b90 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
23ba0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
23bb0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
23bc0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23bd0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23be0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23bf0 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
23c00 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
23c10 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
23c20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
23c30 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
23c40 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
23c50 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
23c60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
23c70 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
23c80 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
23c90 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
23ca0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23cb0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23cc0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
23cd0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
23ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23cf0 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
23d00 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23d10 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
23d20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23d30 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
23d40 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
23d50 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
23d60 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
23d70 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
23d80 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
23d90 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
23da0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
23db0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
23dc0 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
23dd0 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
23de0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
23df0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23e00 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
23e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
23e20 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
23e30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
23e40 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
23e50 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
23e60 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
23e70 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23e80 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
23e90 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
23ea0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
23eb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
23ec0 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
23ed0 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
23ee0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
23ef0 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
23f00 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
23f10 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
23f20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
23f30 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
23f40 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
23f50 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
23f60 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
23f70 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
23f80 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
23f90 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
23fa0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
23fb0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23fc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
23fd0 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
23fe0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23ff0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24000 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
24010 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
24020 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
24030 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
24040 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
24050 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
24060 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
24070 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
24080 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
24090 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
240a0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
240b0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
240c0 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
240d0 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
240e0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
240f0 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
24100 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
24110 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
24120 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
24130 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
24140 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
24150 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
24160 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
24170 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
24180 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
24190 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
241a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
241b0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
241c0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
241d0 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
241e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
241f0 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
24200 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
24210 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
24220 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
24230 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
24240 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24250 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
24260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
24270 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
24280 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
24290 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
242a0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
242b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
242c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
242d0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
242e0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
242f0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
24300 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
24310 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
24320 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
24330 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24340 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
24350 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
24360 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
24370 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
24380 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
24390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
243a0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
243b0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
243c0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
243d0 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
243e0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
243f0 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
24400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24410 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
24420 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
24430 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
24440 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
24450 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24460 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
24470 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
24480 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
24490 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
244a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
244b0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
244c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
244d0 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
244e0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
244f0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
24500 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
24510 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
24520 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
24530 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
24540 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
24550 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
24560 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
24570 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
24580 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
24590 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
245a0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
245b0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
245c0 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
245d0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
245e0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
245f0 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
24600 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
24610 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
24620 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
24630 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
24640 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
24650 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
24660 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24670 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
24680 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
24690 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
246a0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
246b0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
246c0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
246d0 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
246e0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
246f0 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
24700 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
24710 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
24720 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
24730 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
24740 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
24750 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
24760 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
24770 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
24780 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24790 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
247a0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
247b0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
247c0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
247d0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
247e0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
247f0 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
24800 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
24810 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
24820 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
24830 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
24840 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
24850 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
24860 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
24870 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
24880 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
24890 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
248a0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
248b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
248c0 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
248d0 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
248e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
248f0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
24900 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
24910 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
24920 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
24930 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
24940 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
24950 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
24960 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
24970 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
24980 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
24990 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
249a0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
249b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
249c0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
249d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
249e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
249f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
24a00 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
24a10 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
24a20 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
24a30 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
24a40 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
24a50 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
24a60 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
24a70 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
24a80 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
24a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24aa0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
24ab0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
24ac0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24ad0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
24ae0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
24af0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
24b00 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
24b10 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
24b20 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
24b30 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
24b40 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
24b50 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
24b60 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
24b70 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
24b80 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
24b90 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
24ba0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
24bb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
24bc0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
24bd0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
24be0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
24bf0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
24c00 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
24c10 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
24c20 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
24c30 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
24c40 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
24c50 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
24c60 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24c70 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
24c80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
24c90 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
24ca0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
24cb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24cc0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
24cd0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
24ce0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
24cf0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
24d00 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
24d10 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
24d20 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
24d30 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
24d40 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
24d50 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
24d60 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
24d70 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
24d80 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
24d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
24da0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
24db0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
24dc0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
24dd0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
24de0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
24df0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
24e00 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
24e10 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
24e20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
24e30 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
24e40 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
24e50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
24e60 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
24e70 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
24e80 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
24e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24ea0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
24eb0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24ec0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
24ed0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24ee0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
24ef0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
24f00 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
24f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24f20 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
24f30 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
24f40 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
24f50 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
24f60 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24f70 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
24f80 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
24f90 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
24fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24fb0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
24fc0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
24fd0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
24fe0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24ff0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
25000 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
25010 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
25020 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
25030 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
25040 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
25050 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
25060 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25070 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
25080 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
25090 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
250a0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
250b0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
250c0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
250d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
250e0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
250f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
25100 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
25110 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
25120 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
25130 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
25140 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
25150 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
25160 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
25170 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25180 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25190 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
251a0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
251b0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
251c0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
251d0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
251e0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
251f0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
25200 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25210 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
25220 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
25230 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
25240 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
25250 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
25260 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
25270 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
25280 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
25290 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
252a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
252b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
252c0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
252d0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
252e0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
252f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
25300 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
25310 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
25320 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
25330 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
25340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
25350 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
25360 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
25370 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
25380 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
25390 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
253a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
253b0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
253c0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
253d0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
253e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
253f0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
25400 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
25410 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
25420 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
25430 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
25440 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
25450 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
25460 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
25470 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
25480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
25490 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
254a0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
254b0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
254c0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
254d0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
254e0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
254f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
25500 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
25510 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
25520 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
25530 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
25540 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
25550 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
25560 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
25570 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
25580 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
25590 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
255a0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
255b0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
255c0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
255d0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
255e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
255f0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
25600 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25610 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
25620 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25630 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
25640 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
25650 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
25660 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
25670 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25680 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
25690 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
256a0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
256b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
256c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
256d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
256e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
256f0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
25700 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
25710 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
25720 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
25730 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
25740 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
25750 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
25760 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
25770 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
25780 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
25790 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
257a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
257b0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
257c0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
257d0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
257e0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
257f0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
25800 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
25810 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
25820 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
25830 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
25840 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
25850 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
25860 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
25870 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25880 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
25890 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
258a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
258b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
258c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
258d0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
258e0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
258f0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
25900 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
25910 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
25920 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
25930 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
25940 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
25950 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
25960 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
25970 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
25980 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25990 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
259a0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
259b0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
259c0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
259d0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
259e0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
259f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25a00 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
25a10 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
25a20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25a30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25a40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
25a50 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
25a60 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
25a70 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25a80 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
25a90 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
25aa0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
25ab0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
25ac0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
25ad0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
25ae0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
25af0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
25b00 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
25b10 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
25b20 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
25b30 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
25b40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
25b60 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
25b70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25b80 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
25b90 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
25ba0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
25bb0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
25bc0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
25bd0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
25be0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25bf0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
25c00 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25c10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25c20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
25c30 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
25c40 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
25c50 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25c60 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
25c70 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
25c80 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
25c90 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
25ca0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
25cb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25cc0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
25cd0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25cf0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
25d00 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
25d10 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
25d20 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
25d30 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
25d40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25d50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25d60 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
25d70 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
25d80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
25d90 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
25da0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25db0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25dc0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
25dd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25de0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
25df0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
25e00 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
25e10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25e20 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
25e30 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25e40 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
25e50 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
25e60 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
25e70 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25e80 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
25e90 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
25ea0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
25eb0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
25ec0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
25ed0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
25ee0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
25ef0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25f00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
25f10 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25f20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
25f30 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
25f40 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
25f50 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
25f60 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
25f70 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
25f80 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
25f90 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
25fa0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25fb0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
25fc0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
25fd0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
25fe0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
25ff0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
26000 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
26010 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
26020 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
26030 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
26040 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
26050 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
26060 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
26070 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
26080 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
26090 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
260a0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
260b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
260c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
260d0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
260e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
260f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
26100 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
26110 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
26120 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
26130 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
26140 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
26150 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
26160 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
26170 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
26180 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26190 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
261a0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
261b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
261c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
261d0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
261e0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
261f0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
26200 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
26210 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
26220 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
26230 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26240 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26250 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
26260 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
26270 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
26280 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
26290 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
262a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
262b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
262c0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
262d0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
262e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
262f0 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69  ption..** URI fi
26300 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
26310 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
26320 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
26330 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
26340 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
26350 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
26360 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
26370 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
26380 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
26390 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
263a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
263b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
263c0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
263d0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
263e0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
263f0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
26400 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
26410 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
26420 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
26430 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
26440 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
26450 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
26460 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
26470 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
26480 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
26490 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
264a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
264b0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
264c0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
264d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
264e0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
264f0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
26500 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
26510 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
26520 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
26530 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
26540 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
26550 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
26560 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
26570 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
26580 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
26590 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
265a0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
265b0 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
265c0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
265d0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
265e0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
265f0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
26600 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
26610 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
26620 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
26630 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
26640 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26650 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
26660 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
26670 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
26680 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
26690 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
266a0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
266b0 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
266c0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
266d0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
266e0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
266f0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
26700 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
26710 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
26720 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
26730 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
26740 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
26750 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
26760 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
26770 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
26780 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
26790 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
267a0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
267b0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
267c0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
267d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
267e0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
267f0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
26800 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
26810 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
26820 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
26830 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
26840 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
26850 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
26860 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
26870 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
26880 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
26890 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
268a0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
268b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
268c0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
268d0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
268e0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
268f0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
26900 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
26910 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
26920 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
26930 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26940 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
26950 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
26960 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
26970 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
26980 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
26990 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
269a0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
269b0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
269c0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
269d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
269e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
269f0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26a00 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
26a10 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
26a20 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26a30 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
26a40 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
26a50 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
26a60 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
26a70 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
26a80 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
26a90 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
26aa0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
26ab0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
26ac0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26ad0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
26ae0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
26af0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
26b00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
26b10 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
26b20 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
26b30 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
26b40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
26b50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
26b60 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
26b70 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
26b80 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
26b90 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26ba0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
26bb0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
26bc0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
26bd0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
26be0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26bf0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
26c00 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
26c10 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
26c20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
26c30 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
26c40 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
26c50 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26c60 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
26c70 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
26c80 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
26c90 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
26ca0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
26cb0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
26cc0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
26cd0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
26ce0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
26cf0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
26d00 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
26d10 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
26d20 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
26d30 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
26d40 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
26d50 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
26d60 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
26d70 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
26d80 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
26d90 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
26da0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26db0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26dc0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
26dd0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
26de0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26df0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
26e00 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
26e10 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
26e20 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
26e30 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
26e40 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26e50 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
26e60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26e70 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
26e80 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
26e90 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
26ea0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
26eb0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
26ec0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
26ed0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
26ee0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
26ef0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
26f00 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
26f10 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
26f20 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
26f30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26f40 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26f50 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
26f60 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
26f70 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
26f80 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
26f90 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
26fa0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
26fb0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
26fc0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
26fd0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
26fe0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26ff0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
27000 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
27010 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
27020 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
27030 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
27040 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
27050 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
27060 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
27070 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
27080 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
27090 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
270a0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
270b0 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
270c0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
270d0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
270e0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
270f0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
27100 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
27110 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
27120 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
27130 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
27140 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
27150 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
27160 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
27170 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
27180 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
27190 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
271a0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
271b0 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
271c0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
271d0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
271e0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
271f0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
27200 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
27210 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
27220 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
27230 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
27240 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
27250 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
27260 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
27270 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
27280 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
27290 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
272a0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
272b0 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
272c0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
272d0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
272e0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
272f0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
27300 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
27310 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
27320 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
27330 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
27340 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
27350 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
27360 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
27370 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
27380 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
27390 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
273a0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
273b0 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
273c0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
273d0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
273e0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
273f0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
27400 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
27410 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
27420 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
27430 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
27440 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
27450 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
27460 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
27470 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
27480 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
27490 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
274a0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
274b0 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
274c0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
274d0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
274e0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
274f0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
27500 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
27510 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
27520 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
27530 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
27540 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
27550 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
27560 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
27570 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
27580 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
27590 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
275a0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
275b0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
275c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
275d0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
275e0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
275f0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
27600 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
27610 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
27620 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
27630 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
27640 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
27650 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
27660 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
27670 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27680 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
27690 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
276a0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
276b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
276c0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
276d0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
276e0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
276f0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
27700 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
27710 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
27720 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
27730 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
27740 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
27750 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27760 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
27770 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
27780 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
27790 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
277a0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
277b0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
277c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
277d0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
277e0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
277f0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
27800 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
27810 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
27820 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
27830 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
27840 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
27850 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
27860 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
27870 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
27880 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
27890 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
278a0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
278b0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
278c0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
278d0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
278e0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
278f0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
27900 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
27910 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
27920 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
27930 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
27940 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
27950 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
27960 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
27970 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
27980 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
27990 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
279a0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
279b0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
279c0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
279d0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
279e0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
279f0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
27a00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27a10 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
27a20 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
27a30 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
27a40 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
27a50 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
27a60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
27a70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27a80 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
27a90 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
27aa0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
27ab0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27ac0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
27ad0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
27ae0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
27af0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
27b00 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
27b10 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
27b20 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
27b30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27b40 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
27b50 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
27b60 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
27b70 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
27b80 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
27b90 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
27ba0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
27bb0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
27bc0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27bd0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
27be0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
27bf0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
27c00 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
27c10 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
27c20 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
27c30 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27c40 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
27c50 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
27c60 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
27c70 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
27c80 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
27c90 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
27ca0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
27cb0 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
27cc0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
27cd0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
27ce0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
27cf0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
27d00 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
27d10 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
27d20 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
27d30 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27d40 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
27d50 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
27d60 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
27d70 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
27d80 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
27d90 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
27da0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
27db0 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
27dc0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
27dd0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
27de0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
27df0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
27e00 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
27e10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27e20 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
27e30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27e40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27e50 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
27e60 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
27e70 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
27e80 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
27e90 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
27ea0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
27eb0 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
27ec0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
27ed0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
27ee0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
27ef0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
27f00 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
27f10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27f20 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
27f30 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
27f40 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
27f50 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
27f60 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
27f70 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
27f80 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
27f90 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
27fa0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
27fb0 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
27fc0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
27fd0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
27fe0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
27ff0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
28000 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
28010 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
28020 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
28030 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
28040 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
28050 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
28060 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
28070 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
28080 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
28090 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
280a0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
280b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
280c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
280d0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
280e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
280f0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
28100 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
28110 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
28120 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
28130 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
28140 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
28150 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
28160 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
28170 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
28180 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
28190 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
281a0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
281b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
281c0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
281d0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
281e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
281f0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
28200 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
28210 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
28220 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
28230 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
28240 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
28250 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
28260 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
28270 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
28280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
28290 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
282a0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
282b0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
282c0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
282d0 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
282e0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
282f0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
28300 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
28310 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
28320 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
28330 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
28340 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
28350 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
28360 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
28370 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
28380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
28390 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
283a0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
283b0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
283c0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
283d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
283e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
283f0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
28400 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
28410 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
28420 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
28430 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
28440 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28450 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
28460 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
28470 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
28480 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
28490 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
284a0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
284b0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
284c0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
284d0 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
284e0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
284f0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
28500 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
28510 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28520 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
28530 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
28540 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
28550 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28560 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28570 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
28580 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
28590 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
285a0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
285b0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
285c0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
285d0 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
285e0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
285f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28600 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
28610 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
28620 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
28630 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
28640 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
28650 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
28660 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
28670 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
28680 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
28690 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
286a0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
286b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
286c0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
286d0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
286e0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
286f0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
28700 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
28710 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
28720 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
28730 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
28740 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
28750 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
28760 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
28770 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
28780 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
28790 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
287a0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
287b0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
287c0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
287d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
287e0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
287f0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
28800 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
28810 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
28820 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
28830 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
28840 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
28850 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
28860 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
28870 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
28880 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
28890 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
288a0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
288b0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
288c0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
288d0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
288e0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
288f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
28900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28910 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28920 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
28930 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
28940 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28950 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
28960 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
28970 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
28980 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
28990 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
289a0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
289b0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
289c0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
289d0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
289e0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
289f0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
28a00 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
28a10 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
28a20 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
28a30 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
28a40 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
28a50 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
28a60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28a70 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
28a80 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
28a90 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
28aa0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28ab0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
28ac0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28ad0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
28ae0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
28af0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
28b00 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
28b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
28b20 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
28b30 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
28b40 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
28b50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
28b60 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
28b70 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
28b80 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
28b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28ba0 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
28bb0 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
28bc0 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
28bd0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
28be0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
28bf0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
28c00 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
28c10 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
28c20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
28c30 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
28c40 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
28c50 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
28c60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
28c70 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
28c80 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
28c90 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
28ca0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28cb0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
28cc0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
28cd0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
28ce0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
28cf0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
28d00 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
28d10 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
28d20 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
28d30 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
28d40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28d50 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
28d60 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
28d70 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
28d80 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
28d90 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
28da0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
28db0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
28dc0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
28dd0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
28de0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
28df0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
28e00 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
28e10 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
28e20 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
28e30 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
28e40 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
28e50 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
28e60 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
28e70 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
28e80 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
28e90 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
28ea0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
28eb0 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
28ec0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
28ed0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
28ee0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
28ef0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
28f00 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
28f10 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
28f20 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
28f30 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
28f40 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
28f50 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28f60 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28f70 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28f80 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28f90 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
28fa0 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
28fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
28fc0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
28fd0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
28fe0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
28ff0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
29000 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
29010 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
29020 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
29030 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
29040 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
29050 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
29060 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
29070 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
29080 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
29090 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
290a0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
290b0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
290c0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
290d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
290e0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
290f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
29100 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
29110 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
29120 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
29130 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
29140 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
29150 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
29160 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
29170 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
29180 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
29190 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
291a0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
291b0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
291c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
291d0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
291e0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
291f0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
29200 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
29210 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
29220 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
29230 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
29240 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
29250 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
29260 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
29270 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
29280 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
29290 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
292a0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
292b0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
292c0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
292d0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
292e0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
292f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
29300 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
29310 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
29320 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
29330 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
29340 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
29350 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
29360 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29370 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
29380 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
29390 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
293a0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
293b0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
293c0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
293d0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
293e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
293f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
29400 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
29410 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
29420 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
29430 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
29440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
29450 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
29460 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
29470 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
29480 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
29490 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
294a0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
294b0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
294c0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
294d0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
294e0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
294f0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
29500 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
29510 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29520 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
29530 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
29540 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
29550 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
29560 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
29570 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
29580 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
29590 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
295a0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
295b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
295c0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
295d0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
295e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
295f0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
29600 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29610 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
29620 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29630 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
29640 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
29650 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
29660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29670 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
29680 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
29690 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
296a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
296b0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
296c0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
296d0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
296e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
296f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
29700 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
29710 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
29720 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
29730 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
29740 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
29750 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
29760 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29770 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
29780 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
29790 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
297a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
297b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
297c0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
297d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
297e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
297f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
29800 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
29810 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
29820 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
29830 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
29840 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
29850 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
29860 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29870 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
29880 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
29890 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
298a0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
298b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
298c0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
298d0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
298e0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
298f0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
29900 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
29910 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
29920 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
29930 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29940 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
29950 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
29960 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
29970 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
29980 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
29990 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
299a0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
299b0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
299c0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
299d0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
299e0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
299f0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
29a00 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
29a10 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
29a20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
29a30 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
29a40 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
29a50 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
29a60 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
29a70 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
29a80 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
29a90 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
29aa0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
29ab0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
29ac0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
29ad0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
29ae0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
29af0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
29b00 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
29b10 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
29b20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
29b30 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
29b40 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
29b50 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29b60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
29b70 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
29b80 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
29b90 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
29ba0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
29bb0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
29bc0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
29bd0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
29be0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
29bf0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
29c00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29c10 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
29c20 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
29c30 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
29c40 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
29c50 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
29c60 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
29c70 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
29c80 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
29c90 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
29ca0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
29cb0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
29cc0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
29cd0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
29ce0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
29cf0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
29d00 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
29d10 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
29d20 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
29d30 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
29d40 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
29d50 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
29d60 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
29d70 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
29d80 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
29d90 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
29da0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
29db0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
29dc0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
29dd0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
29de0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
29df0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
29e00 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
29e10 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29e20 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29e30 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
29e40 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
29e50 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
29e60 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
29e70 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
29e80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
29e90 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
29ea0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
29eb0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
29ec0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
29ed0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
29ee0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
29ef0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
29f00 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
29f10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
29f20 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
29f30 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
29f40 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
29f50 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
29f60 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
29f70 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
29f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
29f90 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
29fa0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
29fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29fc0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
29fd0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
29fe0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
29ff0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
2a000 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
2a010 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2a020 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2a030 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
2a040 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
2a050 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
2a060 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
2a070 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2a080 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
2a090 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
2a0a0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
2a0b0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
2a0c0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
2a0d0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2a0e0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
2a0f0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
2a100 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
2a110 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2a120 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2a130 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2a140 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
2a150 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a160 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
2a170 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
2a180 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
2a190 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
2a1a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a1b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
2a1c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a1d0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
2a1e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a1f0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
2a200 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
2a210 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
2a220 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a230 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2a240 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a250 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
2a260 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a270 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2a280 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
2a290 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
2a2a0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
2a2b0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2a2c0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
2a2d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2a2e0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
2a2f0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
2a300 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
2a310 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
2a320 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a330 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
2a340 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a350 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
2a360 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a370 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2a380 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
2a390 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
2a3a0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a3b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a3c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
2a3d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a3e0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a3f0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
2a400 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a410 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
2a420 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
2a430 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
2a440 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a450 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
2a460 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a470 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
2a480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a490 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
2a4a0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
2a4b0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
2a4c0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
2a4d0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
2a4e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
2a4f0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   If [sqlite3_pre
2a500 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
2a510 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
2a520 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74  tries to allocat
2a530 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65  e space for more
2a540 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20   than this many 
2a550 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20  opcodes.** in a 
2a560 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20  single prepared 
2a570 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51  statement, an SQ
2a580 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72  LITE_NOMEM error
2a590 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
2a5a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a5b0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a5c0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
2a5d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2a5e0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
2a5f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a600 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2a610 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
2a620 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2a630 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a640 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
2a650 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
2a660 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
2a670 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a680 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
2a690 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
2a6a0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
2a6b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a6c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2a6d0 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
2a6e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a6f0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2a700 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a710 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2a720 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
2a730 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
2a740 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
2a750 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
2a760 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a770 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a780 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
2a790 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2a7a0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2a7b0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
2a7c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
2a7d0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
2a7e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
2a7f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2a800 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
2a810 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a820 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2a830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2a840 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
2a850 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a860 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
2a870 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
2a880 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a890 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
2a8a0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
2a8b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a8c0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2a8d0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
2a8e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a8f0 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
2a900 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
2a910 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
2a920 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a930 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
2a940 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
2a950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a960 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
2a970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a980 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2a990 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2a9a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2a9b0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2a9c0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
2a9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9e0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2a9f0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2aa00 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
2aa10 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2aa20 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2aa30 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
2aa40 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2aa50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2aa60 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
2aa70 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
2aa80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2aa90 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
2aaa0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
2aab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2aac0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
2aad0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
2aae0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
2aaf0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2ab00 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
2ab10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2ab20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
2ab30 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
2ab40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ab50 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
2ab60 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
2ab70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ab80 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
2ab90 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
2aba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
2abb0 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a  epare Flags.**.*
2abc0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2abd0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
2abe0 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20   flags that can 
2abf0 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  be passed into.*
2ac00 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61  * "prepFlags" pa
2ac10 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b  rameter of the [
2ac20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ac30 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  v3()] and.** [sq
2ac40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ac50 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v3()] interfaces
2ac60 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67  ..**.** New flag
2ac70 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2ac80 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2ac90 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
2aca0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
2acb0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2acc0 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53  ISTENT]] ^(<dt>S
2acd0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2ace0 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a  RSISTENT</dt>.**
2acf0 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
2ad00 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2ad10 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e  NT flag is a hin
2ad20 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70  t to the query p
2ad30 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74  lanner.** that t
2ad40 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2ad50 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65  ement will be re
2ad60 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e  tained for a lon
2ad70 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72  g time and.** pr
2ad80 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61  obably reused ma
2ad90 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74  ny times.)^ ^Wit
2ada0 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20  hout this flag, 
2adb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2adc0 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  _v3()].** and [s
2add0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ade0 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68  _v3()] assume th
2adf0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
2ae00 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a  statement will .
2ae10 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20  ** be used just 
2ae20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20  once or at most 
2ae30 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20  a few times and 
2ae40 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75  then destroyed u
2ae50 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2ae60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c  _finalize()] rel
2ae70 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68  atively soon. Th
2ae80 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2ae90 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a  entation acts.**
2aea0 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79   on this hint by
2aeb0 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73   avoiding the us
2aec0 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20  e of [lookaside 
2aed0 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f  memory] so as no
2aee0 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20  t to.** deplete 
2aef0 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72  the limited stor
2af00 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
2af10 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65  emory. Future ve
2af20 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c  rsions of.** SQL
2af30 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74  ite may act on t
2af40 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65  his hint differe
2af50 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ntly..** </dl>.*
2af60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2af70 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2af80 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ENT             
2af90 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x01../*.** CAP
2afa0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2afb0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2afc0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2afd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2afe0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2aff0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2b000 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2b010 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2b020 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2b030 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75  statement, it mu
2b040 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
2b050 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
2b060 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
2b070 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
2b080 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f  ese routines.  O
2b090 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  r, in other word
2b0a0 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  s, these routine
2b0b0 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75  s.** are constru
2b0c0 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70  ctors for the [p
2b0d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b0e0 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  t] object..**.**
2b0f0 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72   The preferred r
2b100 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73  outine to use is
2b110 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b120 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a  e_v2()].  The.**
2b130 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b140 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  e()] interface i
2b150 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f  s legacy and sho
2b160 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2b170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b180 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e  are_v3()] has an
2b190 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67   extra "prepFlag
2b1a0 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69  s" option that i
2b1b0 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70  s used.** for sp
2b1c0 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a  ecial purposes..
2b1d0 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66  **.** The use of
2b1e0 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72   the UTF-8 inter
2b1f0 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72  faces is preferr
2b200 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75  ed, as SQLite cu
2b210 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20  rrently.** does 
2b220 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e  all parsing usin
2b230 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54  g UTF-8.  The UT
2b240 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2b250 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
2b260 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  as a convenience
2b270 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2b280 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79  terfaces work by
2b290 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a   converting the.
2b2a0 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e  ** input text in
2b2b0 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69  to UTF-8, then i
2b2c0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72  nvoking the corr
2b2d0 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20  esponding UTF-8 
2b2e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2b2f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
2b300 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
2b310 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b320 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
2b330 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
2b340 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2b350 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2b360 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2b370 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
2b380 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2b390 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
2b3a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2b3b0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
2b3c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
2b3d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
2b3e0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
2b3f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2b400 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
2b410 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
2b420 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
2b430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2b440 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f  pare(), sqlite3_
2b450 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a  prepare_v2(),.**
2b460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b470 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74  pare_v3().** int
2b480 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2b490 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2b4a0 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69  repare16(), sqli
2b4b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b4c0 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b4d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2b4e0 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ) use UTF-16..**
2b4f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
2b500 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
2b510 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
2b520 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
2b530 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
2b540 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
2b550 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
2b560 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
2b570 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2b580 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
2b590 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
2b5a0 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
2b5b0 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
2b5c0 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
2b5d0 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
2b5e0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
2b5f0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
2b600 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
2b610 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
2b620 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
2b630 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
2b640 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
2b650 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
2b660 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
2b670 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b680 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
2b690 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
2b6a0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
2b6b0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
2b6c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
2b6d0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
2b6e0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
2b6f0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2b700 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
2b710 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
2b720 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
2b730 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2b740 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
2b750 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
2b760 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
2b770 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
2b780 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
2b790 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
2b7a0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
2b7b0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
2b7c0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
2b7d0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
2b7e0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
2b7f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2b800 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
2b810 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
2b820 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
2b830 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
2b840 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
2b850 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
2b860 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
2b870 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
2b880 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
2b890 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
2b8a0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
2b8b0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
2b8c0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
2b8d0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
2b8e0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
2b8f0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
2b900 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
2b910 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
2b920 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2b930 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b940 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
2b950 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2b960 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
2b970 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
2b980 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
2b990 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2b9a0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
2b9b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2b9c0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
2b9d0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
2b9e0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2b9f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2ba00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ba10 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v2(), sqlite3_pr
2ba20 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69  epare_v3(), sqli
2ba30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ba40 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2ba50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2ba60 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2ba70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2ba80 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2ba90 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20  s..** The older 
2baa0 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69  interfaces (sqli
2bab0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
2bac0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2bad0 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65  e16()).** are re
2bae0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
2baf0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2bb00 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2bb10 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2bb20 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58  ..** ^In the "vX
2bb30 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2bb40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2bb50 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2bb60 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2bb70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2bb80 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2bb90 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2bba0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2bbb0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2bbc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2bbd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2bbe0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2bbf0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2bc00 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2bc10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2bc20 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2bc30 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2bc40 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2bc50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2bc60 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2bc70 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2bc80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2bc90 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2bca0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2bcb0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2bcc0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2bcd0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2bce0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2bcf0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2bd00 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2bd10 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2bd20 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2bd30 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2bd40 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2bd50 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2bd60 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2bd70 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2bd80 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2bd90 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2bda0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2bdb0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2bdc0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2bdd0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2bde0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2bdf0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2be00 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2be10 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2be20 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2be30 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2be40 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2be50 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2be60 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2be70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2be80 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2be90 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2bea0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2beb0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2bec0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2bed0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2bee0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2bef0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2bf00 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2bf10 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2bf20 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2bf30 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2bf40 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2bf50 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2bf60 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2bf70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2bf80 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2bf90 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2bfa0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2bfb0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2bfc0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2bfd0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2bfe0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2bff0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2c000 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2c010 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2c020 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2c030 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2c040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2c050 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2c060 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2c070 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2c080 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2c090 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2c0a0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2c0b0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2c0c0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2c0d0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2c0e0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2c0f0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2c100 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2c110 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2c120 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2c130 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2c140 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2c150 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2c160 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2c170 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2c180 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2c190 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2c1a0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2c1b0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2c1c0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2c1d0 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2c1e0 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2c1f0 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2c200 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2c210 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2c220 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2c230 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2c240 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2c250 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2c260 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2c270 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2c280 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2c290 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2c2a0 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2c2b0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2c2c0 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2c2d0 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2c2e0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2c2f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2c300 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2c310 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2c320 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c  rameter..** </ol
2c330 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
2c340 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2c350 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c360 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c370 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c380 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2c390 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c3a0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2c3b0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c3c0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c3d0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c3e0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c3f0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c400 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c410 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c420 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c430 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c440 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c450 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c460 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2c470 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2c480 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
2c490 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c4a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c4b0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c4c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c4d0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c4e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c4f0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c500 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c510 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c520 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c530 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c540 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c550 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c560 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c570 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c580 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c590 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c5a0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c5b0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2c5c0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c5d0 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v3(.  sqlite3 
2c5e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c5f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c600 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c610 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c620 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c630 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2c640 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c650 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c660 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c670 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c680 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c690 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2c6a0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c6b0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c6c0 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c6d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c6e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c6f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c700 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c710 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c720 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c730 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c740 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c750 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
2c760 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c770 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c780 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c790 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2c7a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c7b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2c7c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c7d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c7e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c7f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c800 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c810 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c820 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c830 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c840 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c850 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c860 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c870 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c880 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c890 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c8a0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2c8b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c8c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c8d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2c8e0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2c8f0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2c900 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2c910 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2c920 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2c930 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2c940 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2c950 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2c960 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2c970 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2c980 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2c990 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2c9a0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2c9b0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2c9c0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2c9d0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2c9e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a  3_prepare16_v3(.
2c9f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2ca00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2ca10 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2ca20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2ca30 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2ca40 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2ca50 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2ca60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ca70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ca80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ca90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2caa0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2cab0 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2cac0 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2cad0 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2cae0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2caf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cb00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cb10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cb20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2cb30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cb40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cb50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cb60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cb70 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2cb80 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2cb90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2cba0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2cbb0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2cbc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cbd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2cbe0 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2cbf0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2cc00 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2cc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cc20 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2cc30 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
2cc40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2cc50 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2cc60 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v3()],.** [sq
2cc70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2cc80 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
2cc90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2cca0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2ccb0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ccc0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2ccd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2cce0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2ccf0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2cd00 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2cd10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cd20 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2cd30 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2cd40 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2cd50 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2cd60 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2cd70 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2cd80 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2cd90 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2cda0 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2cdb0 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2cdc0 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2cdd0 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2cde0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2cdf0 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2ce00 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2ce10 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2ce20 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2ce30 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2ce40 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2ce50 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2ce60 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2ce70 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2ce80 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2ce90 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2cea0 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2ceb0 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2cec0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2ced0 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2cee0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2cef0 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2cf00 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2cf10 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2cf20 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2cf30 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2cf40 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2cf50 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2cf60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2cf70 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2cf80 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2cf90 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2cfa0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2cfb0 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2cfc0 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2cfd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2cfe0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2cff0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2d000 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2d010 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2d020 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2d030 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2d040 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2d050 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2d060 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2d070 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2d080 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2d090 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2d0a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d0b0 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2d0c0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2d0d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2d0e0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2d0f0 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2d100 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2d110 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2d120 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2d130 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2d140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2d150 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2d160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2d170 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2d180 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2d190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d1a0 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  tmt);.char *sqli
2d1b0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d1c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d1d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d1e0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2d1f0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2d200 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2d210 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2d220 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2d230 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2d240 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2d250 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2d260 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2d270 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2d280 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2d290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d2a0 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2d2b0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2d2c0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2d2d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2d2e0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2d2f0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2d300 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d310 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2d320 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2d330 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2d340 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2d350 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2d360 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2d370 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2d380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2d390 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2d3a0 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2d3b0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2d3c0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2d3d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2d3e0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2d3f0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2d400 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2d410 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2d420 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2d430 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2d440 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2d450 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2d460 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2d470 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2d480 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2d490 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2d4a0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2d4b0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d4c0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2d4d0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2d4e0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2d4f0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2d500 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2d510 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2d520 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2d530 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2d540 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2d550 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2d560 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2d570 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2d580 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d590 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2d5a0 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2d5b0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2d5c0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2d5d0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2d5e0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2d5f0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2d600 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2d610 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2d620 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2d630 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2d640 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2d650 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2d660 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2d670 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2d680 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2d690 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2d6a0 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2d6b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2d6c0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2d6d0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2d6e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d6f0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2d700 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2d710 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2d720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d730 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2d740 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d750 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2d760 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d770 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2d780 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2d790 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2d7a0 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2d7b0 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2d7c0 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2d7d0 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2d7e0 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2d7f0 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2d800 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2d810 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2d820 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2d830 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2d840 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2d850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2d860 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2d870 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d890 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2d8a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2d8b0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2d8c0 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2d8d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d8e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d8f0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2d900 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2d910 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2d920 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2d940 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2d950 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2d960 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2d970 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2d980 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2d990 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2d9a0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2d9b0 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2d9c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2d9d0 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2d9e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d9f0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2da00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2da10 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2da20 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2da30 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2da40 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2da50 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2da60 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2da70 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2da80 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2da90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2daa0 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2dab0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2dac0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2dad0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2dae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2daf0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2db00 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2db10 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2db20 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2db30 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2db40 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2db50 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2db60 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2db70 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2db80 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2db90 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2dba0 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2dbb0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2dbc0 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2dbd0 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2dbe0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2dbf0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2dc00 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2dc10 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2dc20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2dc30 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2dc40 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2dc50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2dc60 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2dc70 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2dc80 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2dc90 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2dca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dcb0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2dcc0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2dcd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dce0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2dcf0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2dd00 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2dd10 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2dd20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2dd30 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2dd40 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2dd50 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2dd60 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2dd70 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2dd80 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2dd90 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2dda0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2ddb0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2ddc0 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2ddd0 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2dde0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2ddf0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2de00 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2de10 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2de20 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2de30 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2de40 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2de50 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2de60 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2de70 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2de80 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2de90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2dea0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2deb0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2dec0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2ded0 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2dee0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2def0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2df00 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2df10 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2df20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2df30 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2df40 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2df50 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2df60 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2df70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2df80 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2df90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dfa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2dfb0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2dfc0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2dfd0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2dfe0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2dff0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2e000 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2e010 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2e020 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e030 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2e040 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2e050 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2e060 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e070 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2e080 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2e090 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2e0a0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2e0b0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2e0c0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2e0d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2e0e0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2e0f0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2e100 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2e110 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2e120 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2e130 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2e140 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2e150 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2e160 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2e170 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2e180 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2e190 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e1a0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e1b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e1c0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2e1d0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2e1e0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2e1f0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2e200 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2e210 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2e220 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2e230 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2e240 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2e250 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2e260 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2e270 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e290 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2e2a0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2e2b0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2e2c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e2d0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2e2e0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2e2f0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2e300 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2e310 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2e320 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e330 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2e340 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2e350 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e360 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2e370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e380 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2e390 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2e3a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e3b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e3c0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2e3d0 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a  d as arguments.*
2e3e0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  * to [sqlite3_re
2e3f0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b  sult_value()], [
2e400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2e410 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ue()], and.** [s
2e420 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2e430 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2e440 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2e450 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2e460 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2e470 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2e480 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2e490 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e4a0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2e4b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e4c0 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33  e3_value sqlite3
2e4d0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2e4e0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2e4f0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2e500 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2e510 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2e520 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2e530 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2e540 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2e550 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2e560 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2e570 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2e580 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2e590 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2e5a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2e5b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e5c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e5d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2e5e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e5f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e600 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2e610 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2e620 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2e630 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e640 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2e650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2e660 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2e670 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e680 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2e690 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2e6a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e6b0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2e6c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e6d0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2e6e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e6f0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2e700 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e710 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2e720 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2e730 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2e740 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2e750 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e760 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2e770 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2e780 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2e790 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2e7a0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2e7b0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2e7c0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2e7d0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2e7e0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2e7f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e800 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2e810 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e820 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2e830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e840 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2e850 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2e860 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2e870 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2e880 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2e890 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2e8a0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2e8b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2e8c0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2e8d0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2e8e0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2e8f0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2e900 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2e910 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2e920 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2e930 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2e940 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2e950 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2e960 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2e970 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2e980 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2e990 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2e9a0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2e9b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2e9c0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2e9d0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2e9e0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2e9f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ea00 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2ea10 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2ea20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2ea30 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2ea40 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2ea50 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2ea60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ea70 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2ea80 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2ea90 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2eaa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2eab0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2eac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2ead0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2eae0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2eaf0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2eb00 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2eb10 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2eb20 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2eb30 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2eb40 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2eb50 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2eb60 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2eb70 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2eb80 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2eb90 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2eba0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2ebb0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2ebc0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2ebd0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2ebe0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2ebf0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2ec00 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2ec10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ec20 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2ec30 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2ec40 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2ec50 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2ec60 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2ec70 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2ec80 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2ec90 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2eca0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2ecb0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2ecc0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2ecd0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ece0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2ecf0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2ed00 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2ed10 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2ed20 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2ed30 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2ed40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2ed50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2ed60 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2ed70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2ed80 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2ed90 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2eda0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2edb0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2edc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2edd0 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2ede0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2edf0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2ee00 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2ee10 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2ee20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2ee30 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2ee40 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2ee50 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ee60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2ee70 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2ee80 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2ee90 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2eea0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2eeb0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2eec0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2eed0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2eee0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2eef0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2ef00 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2ef10 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2ef20 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2ef30 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2ef40 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2ef50 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2ef60 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2ef70 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2ef80 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2ef90 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2efa0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2efb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2efc0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2efd0 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2efe0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2eff0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f000 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2f010 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f020 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2f030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f040 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f050 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2f060 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f070 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2f080 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2f090 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2f0a0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2f0b0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2f0c0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2f0d0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2f0e0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2f0f0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2f100 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2f110 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2f120 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2f130 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2f140 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2f150 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2f160 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2f170 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2f180 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2f190 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2f1a0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2f1b0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2f1c0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2f1d0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2f1e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f1f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f200 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2f210 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2f220 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2f230 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2f240 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2f250 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2f260 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2f270 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2f280 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2f290 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2f2a0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2f2b0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f2c0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2f2d0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2f2e0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2f2f0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2f300 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2f310 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2f320 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2f330 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2f340 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2f350 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2f360 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2f370 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2f380 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2f390 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2f3a0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2f3b0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2f3c0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2f3d0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2f3e0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2f3f0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2f400 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2f410 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2f420 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2f430 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2f440 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2f450 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2f460 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f470 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2f480 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2f490 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2f4a0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2f4b0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2f4c0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2f4d0 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2f4e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2f4f0 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2f500 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f510 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2f520 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f540 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2f550 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2f560 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2f570 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2f580 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2f590 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2f5a0 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2f5b0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2f5c0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2f5d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2f5e0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2f5f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f600 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2f610 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2f620 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2f630 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2f640 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2f650 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2f660 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2f670 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2f680 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2f690 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2f6a0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2f6b0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2f6c0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2f6d0 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2f6e0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2f6f0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2f700 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2f710 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2f720 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2f730 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2f740 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2f750 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2f760 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2f770 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2f780 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2f790 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2f7a0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54  h BLOB..**.** ^T
2f7b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f7c0 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c  pointer(S,I,P,T,
2f7d0 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65  D) routine cause
2f7e0 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d  s the I-th param
2f7f0 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70  eter in.** [prep
2f800 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f810 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c  S to have an SQL
2f820 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20   value of NULL, 
2f830 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a  but to also be.*
2f840 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2f850 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20  h the pointer P 
2f860 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69  of type T.  ^D i
2f870 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
2f880 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20  pointer or.** a 
2f890 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
2f8a0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2f8b0 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20   for P. ^SQLite 
2f8c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a  will invoke the.
2f8d0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  ** destructor D 
2f8e0 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
2f8f0 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e  gument of P when
2f900 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20   it is finished 
2f910 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65  using.** P.  The
2f920 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f   T parameter sho
2f930 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20  uld be a static 
2f940 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62  string, preferab
2f950 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c  ly a string.** l
2f960 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69  iteral. The sqli
2f970 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2f980 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  () routine is pa
2f990 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f  rt of the.** [po
2f9a0 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
2f9b0 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
2f9c0 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
2f9d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2f9e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2f9f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2fa00 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2fa10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2fa20 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2fa30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fa40 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2fa50 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2fa60 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2fa70 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2fa80 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2fa90 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2faa0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2fab0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2fac0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2fad0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2fae0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2faf0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2fb00 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2fb10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fb20 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2fb30 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2fb40 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2fb50 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2fb60 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2fb70 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2fb80 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2fb90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2fba0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2fbb0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2fbc0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2fbd0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2fbe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fbf0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2fc00 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2fc10 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2fc20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2fc30 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2fc40 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2fc50 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2fc60 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2fc70 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2fc80 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2fc90 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2fca0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2fcb0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2fcc0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2fcd0 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2fce0 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2fcf0 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2fd00 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2fd10 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2fd20 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2fd30 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2fd40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2fd50 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2fd60 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2fd70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2fd80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2fd90 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2fda0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2fdb0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2fdc0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2fdd0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2fde0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2fdf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fe00 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2fe10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2fe20 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2fe30 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2fe40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fe50 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2fe60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2fe70 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2fe80 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2fe90 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2fea0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2feb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2fec0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2fed0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2fee0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2fef0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2ff00 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2ff10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ff20 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2ff30 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2ff40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2ff50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2ff60 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2ff70 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2ff80 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2ff90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2ffa0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2ffb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2ffc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ffd0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2ffe0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2fff0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
30000 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30010 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30020 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
30030 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30040 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
30050 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
30060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30070 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
30080 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
30090 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
300a0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
300b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
300c0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
300d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
300e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
300f0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
30100 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
30110 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64  const char*,void
30120 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
30130 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
30140 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
30150 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
30160 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30170 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
30180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30190 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
301a0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
301b0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
301c0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
301d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
301e0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
301f0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
30200 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
30210 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
30220 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
30230 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
30240 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
30250 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
30260 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
30270 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
30280 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
30290 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
302a0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
302b0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
302c0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
302d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
302e0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
302f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
30300 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
30310 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
30320 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
30330 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
30340 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
30350 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
30360 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
30370 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
30380 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
30390 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
303a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
303b0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
303c0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
303d0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
303e0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
303f0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
30400 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
30410 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30430 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30440 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30450 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30460 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
30470 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30480 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30490 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
304a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
304b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
304c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
304d0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
304e0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
304f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30500 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30510 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30520 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
30530 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30540 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
30550 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
30560 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
30570 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30580 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
30590 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
305a0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
305b0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
305c0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
305d0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
305e0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
305f0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
30600 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30610 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
30620 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
30630 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
30640 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
30650 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
30660 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
30670 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
30680 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
30690 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
306a0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
306b0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
306c0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
306d0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
306e0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
306f0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
30700 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
30710 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
30720 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
30730 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
30740 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
30750 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
30760 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
30770 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
30780 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
30790 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
307a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
307b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
307c0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
307d0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
307e0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
307f0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
30800 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
30810 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
30820 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
30830 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
30840 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30850 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
30860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30870 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30880 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30890 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
308a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
308b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
308c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
308d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
308e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
308f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
30900 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30910 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30920 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30930 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
30940 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
30950 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
30960 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
30970 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
30980 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30990 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
309a0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
309b0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
309c0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
309d0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
309e0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
309f0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
30a00 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
30a10 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
30a20 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30a30 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
30a40 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
30a50 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
30a60 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
30a70 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
30a80 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
30a90 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
30aa0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
30ab0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
30ac0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
30ad0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
30ae0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
30af0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30b00 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30b10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30b20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30b30 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30b40 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30b50 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30b60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30b70 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30b80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30b90 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30ba0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30bb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30bc0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
30bd0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
30be0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
30bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30c00 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
30c10 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
30c20 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30c30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30c40 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
30c50 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
30c60 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
30c70 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
30c80 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
30c90 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30ca0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
30cb0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30cc0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30cd0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
30ce0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
30cf0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
30d00 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
30d10 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30d20 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30d30 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30d40 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
30d50 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
30d60 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
30d70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30d80 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30d90 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
30da0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
30db0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
30dc0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
30dd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
30de0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
30df0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
30e00 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
30e10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30e20 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
30e30 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
30e40 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
30e50 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
30e60 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
30e70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
30e80 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
30e90 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
30ea0 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
30eb0 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
30ec0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
30ed0 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
30ee0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
30ef0 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
30f00 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
30f10 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
30f20 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
30f30 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
30f40 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
30f50 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
30f60 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
30f70 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
30f80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30f90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30fa0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
30fb0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
30fc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30fd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30fe0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
30ff0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
31000 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31010 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31020 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31030 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
31040 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
31050 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
31060 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
31070 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
31080 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
31090 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
310a0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
310b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
310c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
310d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
310e0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
310f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31100 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
31110 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31120 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31130 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
31140 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
31150 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31160 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31170 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
31180 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
31190 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
311a0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
311b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
311c0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
311d0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
311e0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
311f0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
31200 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
31210 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
31220 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
31230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31240 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
31250 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
31260 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31270 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31280 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
31290 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
312a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
312b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
312c0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
312d0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
312e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
312f0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
31300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31310 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
31320 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
31330 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
31340 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
31350 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
31360 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
31370 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
31380 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
31390 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
313a0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
313b0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
313c0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
313d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
313e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
313f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
31400 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
31410 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31420 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
31430 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
31440 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
31450 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
31460 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
31470 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
31480 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
31490 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
314a0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
314b0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
314c0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
314d0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
314e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
314f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31500 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31510 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
31520 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
31530 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31540 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31560 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
31570 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
31580 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31590 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
315a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
315b0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
315c0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
315d0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
315e0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
315f0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
31600 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
31610 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
31620 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
31630 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31640 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
31650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
31660 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
31670 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
31680 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
31690 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
316a0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
316b0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
316c0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
316d0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
316e0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
316f0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
31700 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
31710 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
31720 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31730 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
31740 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31750 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
31760 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
31770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
31780 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
31790 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
317a0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
317b0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
317c0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
317d0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
317e0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
317f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31800 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
31810 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
31820 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
31830 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
31840 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
31850 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
31860 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
31870 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
31880 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
31890 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
318a0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
318b0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
318c0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
318d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
318e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
318f0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
31900 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31910 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
31920 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31930 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31940 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
31950 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
31960 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
31970 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
31980 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
31990 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
319a0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
319b0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
319c0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
319d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
319e0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
319f0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
31a00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31a10 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
31a20 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
31a30 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
31a40 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
31a50 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31a60 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
31a70 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
31a80 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
31a90 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
31aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31ab0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
31ac0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
31ad0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
31ae0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
31af0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
31b00 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
31b10 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
31b20 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
31b30 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
31b40 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
31b50 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
31b60 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
31b70 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
31b80 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
31b90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
31ba0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
31bb0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
31bc0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
31bd0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
31be0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
31bf0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
31c00 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
31c10 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
31c20 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31c30 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
31c40 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
31c50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
31c60 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
31c70 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
31c80 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31c90 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
31ca0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
31cb0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
31cc0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
31cd0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31ce0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
31cf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
31d00 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
31d10 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
31d20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
31d30 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31d40 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
31d50 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
31d60 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
31d70 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
31d80 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
31d90 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
31da0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31db0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31dc0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31dd0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
31de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31df0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31e00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31e10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31e20 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31e30 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
31e40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31e50 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31e60 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
31e70 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
31e80 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
31e90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31ea0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
31eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31ec0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
31ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
31ee0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
31ef0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31f00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31f10 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
31f20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31f30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
31f40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
31f50 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
31f60 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
31f70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31f80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31f90 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
31fa0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
31fb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31fc0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
31fd0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
31fe0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
31ff0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
32000 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
32010 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
32020 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
32030 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
32040 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
32050 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
32060 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
32070 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
32080 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
32090 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
320a0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
320b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
320c0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
320d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
320e0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
320f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32100 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
32110 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
32120 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
32130 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
32140 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
32150 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
32160 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
32170 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
32180 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
32190 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
321a0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
321b0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
321c0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
321d0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
321e0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
321f0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
32200 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
32210 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
32220 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
32230 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
32240 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
32250 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
32260 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
32270 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
32280 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
32290 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
322a0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
322b0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
322c0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
322d0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
322e0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
322f0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
32300 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
32310 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
32320 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
32330 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
32340 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
32350 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
32360 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
32370 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
32380 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
32390 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
323a0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
323b0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
323c0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
323d0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
323e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
323f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32400 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
32410 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
32420 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32430 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
32440 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32450 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
32460 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
32470 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
32480 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32490 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
324a0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
324b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
324c0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
324d0 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
324e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
324f0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32500 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32520 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
32530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32540 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
32550 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
32560 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
32570 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
32580 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32590 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
325a0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
325b0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
325c0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
325d0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
325e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
325f0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
32600 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
32610 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
32620 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
32630 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
32640 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
32650 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
32660 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
32670 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
32680 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
32690 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
326a0 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
326b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
326c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
326d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
326e0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
326f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32700 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
32710 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
32720 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
32730 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32740 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
32750 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
32760 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
32770 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
32780 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
32790 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
327a0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
327b0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
327c0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
327d0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
327e0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
327f0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
32800 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
32810 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
32820 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
32830 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
32840 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
32850 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
32860 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
32870 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
32880 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
32890 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
328a0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
328b0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
328c0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
328d0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
328e0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
328f0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
32900 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
32910 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
32920 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
32930 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
32940 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
32950 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
32960 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
32970 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
32980 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
32990 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
329a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
329b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
329c0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
329d0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
329e0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
329f0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
32a00 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
32a10 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
32a20 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
32a30 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
32a40 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
32a50 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
32a60 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
32a70 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
32a80 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
32a90 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
32aa0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
32ab0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
32ac0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
32ad0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
32ae0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
32af0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32b00 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
32b10 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
32b20 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
32b30 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
32b40 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
32b50 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
32b60 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
32b70 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
32b80 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
32b90 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
32ba0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
32bb0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
32bc0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
32bd0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
32be0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
32bf0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
32c00 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
32c10 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
32c20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32c30 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
32c40 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
32c50 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
32c60 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
32c70 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
32c80 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
32c90 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
32ca0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
32cb0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
32cc0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
32cd0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32ce0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32cf0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
32d00 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
32d10 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
32d20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32d30 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
32d40 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
32d50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
32d60 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32d70 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
32d80 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
32d90 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
32da0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
32db0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
32dc0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
32dd0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
32de0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
32df0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32e00 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
32e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32e20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
32e30 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
32e40 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32e50 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
32e60 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
32e70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
32e80 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
32e90 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
32ea0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
32eb0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
32ec0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
32ed0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
32ee0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
32ef0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32f00 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
32f10 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
32f20 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
32f30 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
32f40 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
32f50 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
32f60 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
32f70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
32f80 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
32f90 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
32fa0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
32fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32fc0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
32fd0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
32fe0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
32ff0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
33000 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
33010 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
33020 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
33030 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
33040 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
33050 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33060 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
33070 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
33080 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
33090 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
330a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
330b0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
330c0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
330d0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
330e0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
330f0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
33100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33110 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
33120 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
33130 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
33140 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
33150 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
33160 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
33170 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
33180 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
33190 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
331a0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
331b0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
331c0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
331d0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
331e0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
331f0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
33200 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
33210 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
33220 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
33230 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
33240 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
33250 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
33260 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
33270 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
33280 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
33290 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
332a0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
332b0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
332c0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
332d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
332e0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
332f0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
33300 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
33310 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
33320 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
33330 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
33340 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
33350 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
33360 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
33370 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
33380 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
33390 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
333a0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
333b0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
333c0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
333d0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
333e0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
333f0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
33400 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33420 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
33430 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
33440 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33450 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
33460 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
33470 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
33480 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
33490 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
334a0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
334b0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
334c0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
334d0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
334e0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
334f0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
33500 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
33510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
33520 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33530 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
33540 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33550 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
33560 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33570 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
33580 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
33590 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
335a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
335b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
335c0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
335d0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
335e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
335f0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
33600 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
33610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
33620 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
33630 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
33640 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
33650 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
33660 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
33670 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33680 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
33690 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
336a0 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
336b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
336c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
336d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
336e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
336f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
33700 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
33710 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
33720 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33730 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
33740 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
33750 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
33760 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
33770 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
33780 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
33790 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
337a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
337b0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
337c0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
337d0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
337e0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
337f0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
33800 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
33810 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33820 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
33830 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
33840 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33860 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33870 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
33880 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
33890 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
338a0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
338b0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
338c0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
338d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
338e0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
338f0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
33900 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
33910 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33920 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
33930 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
33940 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
33950 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
33960 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
33970 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
33980 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
33990 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
339a0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
339b0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
339c0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
339d0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
339e0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
339f0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33a00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33a10 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
33a20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33a40 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
33a50 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
33a60 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
33a70 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
33a80 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
33a90 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
33aa0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
33ab0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
33ac0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33ad0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33ae0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
33af0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
33b00 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
33b10 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
33b20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
33b30 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
33b40 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33b50 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
33b60 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
33b70 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
33b80 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
33b90 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
33ba0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
33bb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33bc0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
33bd0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
33be0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
33bf0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
33c00 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
33c10 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
33c20 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
33c30 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
33c40 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
33c50 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
33c60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33c70 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
33c80 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
33c90 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
33ca0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
33cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33cc0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
33cd0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
33ce0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
33cf0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
33d00 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
33d10 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
33d20 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
33d30 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
33d40 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
33d50 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
33d60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
33d70 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33d80 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
33d90 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33da0 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
33db0 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
33dc0 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
33dd0 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
33de0 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
33df0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
33e00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e10 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
33e20 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
33e30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
33e50 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
33e60 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
33e70 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33e90 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
33ea0 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
33eb0 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
33ec0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33ed0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
33ee0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
33ef0 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
33f00 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33f10 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33f20 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
33f30 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
33f40 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
33f50 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33f60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
33f70 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
33f80 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
33f90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
33fb0 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
33fc0 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
33fd0 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
33fe0 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
33ff0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34000 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
34010 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
34020 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
34030 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
34040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34050 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
34060 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
34070 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
34080 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
34090 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
340a0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
340b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
340c0 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
340d0 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
340e0 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
340f0 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
34100 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
34110 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34120 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
34130 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
34140 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
34150 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
34160 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
34170 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
34180 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
34190 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
341a0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
341b0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
341c0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
341d0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
341e0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
341f0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
34200 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
34210 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
34220 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
34230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34240 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
34250 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
34260 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
34270 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
34280 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
34290 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
342a0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
342b0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
342c0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
342d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
342e0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
342f0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
34300 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
34310 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
34320 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
34330 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
34340 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
34350 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
34360 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
34370 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
34380 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
34390 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
343a0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
343b0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
343c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
343d0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
343e0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
343f0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
34400 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
34410 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
34420 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
34430 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
34440 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
34450 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
34460 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
34470 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
34480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34490 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
344a0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
344b0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
344c0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
344d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
344e0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
344f0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
34500 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
34510 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34520 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
34530 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34540 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
34550 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
34560 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
34570 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
34580 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
34590 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
345a0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
345b0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
345c0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
345d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
345e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
345f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
34600 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
34610 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
34620 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
34630 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
34640 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
34650 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
34660 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34670 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34680 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
34690 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
346a0 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
346b0 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
346c0 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
346d0 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
346e0 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
346f0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
34700 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
34710 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
34720 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
34730 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
34740 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
34750 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
34760 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
34770 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
34780 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
34790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
347a0 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
347b0 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
347c0 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
347d0 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
347e0 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
347f0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
34800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34820 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
34830 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
34840 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
34850 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
34860 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
34870 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
34880 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
34890 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
348a0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
348b0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
348c0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
348d0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
348e0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
348f0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
34900 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
34910 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
34920 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
34930 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
34940 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
34950 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
34960 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
34970 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
34980 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
34990 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
349a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
349b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
349c0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
349d0 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
349e0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
349f0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
34a00 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
34a10 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
34a20 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
34a30 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
34a40 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
34a50 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
34a60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34a70 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
34a80 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
34a90 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
34aa0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
34ab0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
34ac0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34ad0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
34af0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
34b00 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
34b10 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
34b20 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
34b30 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
34b50 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
34b60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
34b70 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
34b80 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
34b90 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
34ba0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
34bc0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
34bd0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
34be0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34c00 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
34c10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34c20 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34c30 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34c40 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34c50 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
34c60 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
34c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34c80 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
34c90 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
34ca0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
34cb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34cc0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34cd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34ce0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34cf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34d00 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
34d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34d20 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34d30 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34d40 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
34d50 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
34d60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34d70 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
34d80 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34d90 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
34da0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34db0 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
34dc0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34dd0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34de0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
34df0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
34e00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34e10 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
34e20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34e30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34e40 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
34e50 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
34e60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34e70 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
34e80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34e90 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
34ea0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
34eb0 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
34ec0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
34ed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34ee0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
34ef0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
34f00 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
34f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34f20 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
34f30 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
34f40 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
34f50 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
34f60 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
34f70 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
34f80 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34f90 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
34fa0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
34fb0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
34fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34fd0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
34fe0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
34ff0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
35000 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35010 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
35020 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
35030 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
35040 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
35050 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
35060 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
35070 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
35080 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
35090 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
350a0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
350b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
350c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
350d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
350e0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
350f0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
35100 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
35110 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
35120 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
35130 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
35140 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35150 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
35160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35170 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
35180 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
35190 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
351a0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
351b0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
351c0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
351d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
351e0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
351f0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
35200 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
35210 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
35220 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
35230 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35240 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
35250 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
35260 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35270 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
35280 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
35290 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
352a0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
352b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
352c0 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
352d0 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
352e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
352f0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
35300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35310 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
35320 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
35330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35340 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
35350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35360 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
35370 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
35380 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
35390 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
353a0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
353b0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
353c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
353d0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
353e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
353f0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
35400 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
35410 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
35420 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
35430 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
35440 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
35450 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
35460 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
35470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35480 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
35490 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
354a0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
354b0 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
354c0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
354d0 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
354e0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
354f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35500 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
35510 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
35520 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
35530 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
35540 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
35550 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
35560 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
35570 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
35580 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
35590 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
355a0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
355b0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
355c0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
355d0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
355e0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
355f0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
35600 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
35610 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
35620 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
35630 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
35640 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
35650 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
35660 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
35670 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
35680 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
35690 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
356a0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
356b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
356c0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
356d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
356e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
356f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35700 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
35710 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
35720 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
35730 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
35740 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
35750 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35760 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
35770 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
35780 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
35790 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
357a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
357b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
357c0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
357d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
357e0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
357f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
35800 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
35810 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
35820 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35830 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35840 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
35850 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
35860 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
35870 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35880 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35890 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
358a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
358b0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
358c0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
358d0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
358e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
358f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35900 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
35910 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35920 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35930 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35940 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35950 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35960 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35970 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
35980 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
35990 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
359a0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
359b0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
359c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
359d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
359e0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
359f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35a00 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
35a10 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35a20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35a30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35a40 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35a50 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
35a60 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
35a70 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
35a80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
35a90 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
35aa0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
35ab0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
35ac0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
35ad0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
35ae0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35af0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
35b00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35b10 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
35b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35b30 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
35b40 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
35b50 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
35b60 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
35b70 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
35b80 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
35b90 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
35ba0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35bb0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35bc0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
35bd0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35be0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
35bf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35c00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35c10 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
35c20 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
35c30 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
35c40 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
35c50 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
35c60 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
35c70 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
35c80 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35c90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35ca0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35cc0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
35cd0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35ce0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35cf0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
35d00 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
35d10 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35d20 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
35d30 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
35d40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
35d50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
35d60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
35d70 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
35d80 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
35d90 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
35da0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
35db0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
35dc0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
35dd0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
35de0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
35df0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
35e00 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
35e10 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
35e20 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
35e30 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
35e40 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35e50 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
35e60 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
35e70 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
35e80 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
35e90 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
35ea0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
35eb0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
35ec0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
35ed0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
35ee0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
35ef0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
35f00 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
35f10 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
35f20 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
35f30 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
35f40 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
35f50 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
35f60 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
35f70 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
35f80 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
35f90 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
35fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35fb0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
35fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35fd0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
35fe0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
35ff0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
36000 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36010 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
36020 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
36030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36040 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
36050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36060 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
36070 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
36080 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
36090 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
360a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
360b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
360c0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
360d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
360e0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
360f0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
36100 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
36110 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
36120 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
36130 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
36140 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36150 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
36160 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
36170 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
36180 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
36190 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
361a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
361b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
361c0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
361d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
361e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
361f0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
36200 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
36210 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
36220 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
36230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36240 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
36250 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
36260 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
36270 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
36280 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
36290 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
362a0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
362b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
362c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
362d0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
362e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
362f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
36300 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
36310 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
36320 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
36330 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
36340 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
36350 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
36360 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
36370 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36380 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
36390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
363a0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
363b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
363c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
363d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
363e0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
363f0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
36400 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
36410 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36420 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
36430 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
36440 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
36450 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
36460 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
36470 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
36480 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
36490 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
364a0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
364b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
364c0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
364d0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
364e0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
364f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36520 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
36530 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36540 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36550 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36560 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
36570 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
36580 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36590 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
365a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
365b0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
365c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
365d0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
365e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
365f0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
36600 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36610 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
36620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36630 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
36640 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
36650 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
36660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
36670 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
36680 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36690 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
366a0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
366b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
366c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
366d0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
366e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
366f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36700 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36710 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36720 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
36730 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36740 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36750 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
36760 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
36770 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36780 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36790 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
367a0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
367b0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
367c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
367d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
367e0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
367f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36800 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36810 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
36820 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
36830 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36840 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
36850 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
36860 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
36870 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36880 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36890 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
368a0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
368b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
368c0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
368d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
368e0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
368f0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36900 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36910 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36920 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36930 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36940 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36950 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36960 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36970 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36980 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
36990 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
369a0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
369b0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
369c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
369d0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
369e0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
369f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36a00 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36a10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36a20 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36a30 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36a40 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36a50 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36a60 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36a70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36a80 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
36aa0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36ab0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36ad0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
36ae0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36af0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36b00 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36b10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36b20 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36b30 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36b40 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36b50 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36b60 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
36b70 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
36b80 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36b90 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36ba0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
36bb0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
36bc0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
36bd0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
36be0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36bf0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36c00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36c10 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
36c20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
36c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36c40 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
36c50 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36c60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36c70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
36c80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
36c90 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36ca0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36cb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36cc0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36cd0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36ce0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36cf0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
36d00 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
36d10 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
36d20 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
36d30 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
36d40 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
36d50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36d60 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
36d70 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
36d80 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
36d90 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
36da0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36db0 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36dc0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36dd0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36de0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36df0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
36e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36e10 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
36e20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
36e30 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
36e40 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
36e50 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36e60 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
36e70 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
36e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
36e90 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
36ea0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
36eb0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
36ec0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36ed0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
36ee0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
36ef0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
36f00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
36f10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36f20 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
36f30 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36f40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36f50 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
36f60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
36f70 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
36f80 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
36f90 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
36fa0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
36fb0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
36fc0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
36fd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36fe0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
36ff0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
37000 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
37010 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
37020 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
37030 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
37040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37050 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
37060 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
37070 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
37080 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37090 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
370a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
370b0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
370c0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
370d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
370e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
370f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37100 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
37110 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37120 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37130 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
37140 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37150 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
37160 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
37170 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
37180 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
37190 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
371a0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
371b0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
371c0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
371d0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
371e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
371f0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
37200 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37210 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
37220 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
37230 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
37240 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
37250 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
37260 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
37270 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37280 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
37290 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
372a0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
372b0 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
372c0 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
372d0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
372e0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
372f0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37300 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
37310 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37320 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
37330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37340 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
37350 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
37360 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
37370 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
37380 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
37390 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
373a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
373b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
373c0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
373d0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
373e0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
373f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
37400 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37410 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
37420 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37430 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
37440 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
37450 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
37460 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
37470 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
37480 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
37490 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
374a0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
374b0 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
374c0 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
374d0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
374e0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
374f0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
37500 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
37510 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
37520 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
37530 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
37540 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
37550 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
37560 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
37570 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
37580 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
37590 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
375a0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
375b0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
375c0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
375d0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
375e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
375f0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
37600 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
37610 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
37620 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
37630 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37640 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
37650 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
37660 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
37670 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
37680 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
37690 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
376a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
376b0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
376c0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
376d0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
376e0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
376f0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
37700 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
37710 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
37720 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
37730 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
37740 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
37750 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
37760 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
37770 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
37780 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
37790 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
377a0 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
377b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
377c0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
377d0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
377e0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
377f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
37800 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
37810 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37820 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
37830 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
37840 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
37850 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
37860 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
37870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37880 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
37890 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
378a0 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
378b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
378c0 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
378d0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
378e0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
378f0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
37900 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37910 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
37920 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
37930 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
37940 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
37950 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
37960 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
37970 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
37980 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
37990 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
379a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
379b0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
379c0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
379d0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
379e0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
379f0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
37a00 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37a10 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
37a20 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37a30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
37a40 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
37a50 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
37a60 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
37a70 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
37a80 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
37a90 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37aa0 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
37ab0 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
37ac0 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
37ad0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
37ae0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
37af0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
37b00 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
37b10 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
37b20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
37b30 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
37b40 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
37b50 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
37b60 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
37b70 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
37b80 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
37b90 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
37ba0 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
37bb0 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
37bc0 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
37bd0 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
37be0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
37bf0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
37c00 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
37c10 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
37c20 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
37c30 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
37c40 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
37c50 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
37c60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37c70 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
37c80 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
37c90 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
37ca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
37cb0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
37cc0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
37cd0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
37ce0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
37cf0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
37d00 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
37d10 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
37d20 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
37d30 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
37d40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37d50 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
37d60 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
37d70 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37d80 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
37d90 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
37da0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
37db0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
37dc0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
37dd0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
37de0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
37df0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
37e00 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37e10 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
37e30 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
37e40 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
37e50 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
37e60 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
37e70 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
37e80 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
37e90 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
37ea0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
37eb0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
37ec0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
37ed0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
37ee0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
37ef0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
37f00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37f10 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
37f20 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
37f30 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
37f40 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
37f50 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37f60 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
37f70 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
37f80 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
37f90 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
37fa0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
37fb0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
37fc0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
37fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
37fe0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
37ff0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
38000 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
38010 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
38020 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38030 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
38040 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
38050 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
38060 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
38070 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
38080 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
38090 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
380a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
380b0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
380c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
380d0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
380e0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
380f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38100 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38110 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
38120 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
38130 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
38140 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
38150 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
38160 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
38170 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
38180 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
38190 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
381a0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
381b0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
381c0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
381d0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
381e0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
381f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38200 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
38210 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
38220 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
38230 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
38240 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
38250 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38260 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
38270 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
38280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
38290 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
382a0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
382b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
382c0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
382d0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
382e0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
382f0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
38300 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
38310 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
38320 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
38330 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
38340 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
38350 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
38360 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
38370 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
38380 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
38390 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
383a0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
383b0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
383c0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
383d0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
383e0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
383f0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
38400 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
38410 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
38420 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
38430 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
38440 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
38450 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38460 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
38470 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
38480 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38490 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
384a0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
384b0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
384c0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
384d0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
384e0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
384f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38500 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
38510 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
38520 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
38530 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
38540 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
38550 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
38560 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38570 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
38580 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
38590 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
385a0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
385b0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
385c0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
385d0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
385e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
385f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38600 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
38610 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38620 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
38630 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
38640 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
38650 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
38660 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
38670 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
38680 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
38690 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
386a0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
386b0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
386c0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
386d0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
386e0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
386f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
38700 5f 76 61 6c 75 65