/ Hex Artifact Content
Login

Artifact 87027977f9a5606208ad0527da42f097579c3a9169de61589339c1bbb2894acb:


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 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (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 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (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 52 45 41 44 20 20  ITE_IOERR_READ  
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 31 3c 3c  ITE_IOERR | (1<<
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 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<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 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<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 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
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 34 3c 3c 38 29 29  _IOERR | (4<<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 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
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 35 3c 3c 38 29 29 0a  IOERR | (5<<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 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
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 36 3c 3c 38 29 29 0a 23  OERR | (6<<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 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
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 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
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 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67d0: 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54  OPEN_FILEPROTECT
67e0: 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 20  ION_MASK        
67f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30 30           0x00700
6810: 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64  000../* Reserved
6820: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6840: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6850: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6860: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6870: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6880: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6890: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
68a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
68b0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
68c0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
68d0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
68e0: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
68f0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6900: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6910: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6920: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6930: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6940: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6960: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6970: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
69a0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
69b0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
69c0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
69d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
69e0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
69f0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6a00: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6a10: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6a20: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6a30: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6a40: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6a50: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6a60: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6a70: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6a80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a90: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6aa0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6ab0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6ac0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6ad0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6ae0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6af0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6b00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6b10: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6b20: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6b30: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6b40: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6b50: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6b60: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6b70: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6b80: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6b90: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6ba0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6bb0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6bc0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6bd0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6be0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6bf0: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6c00: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6c10: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6c20: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6c30: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6c40: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6c50: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6c60: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6c70: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6c80: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6c90: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6ca0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6cb0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6cc0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6cd0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6ce0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6cf0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6d00: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6d10: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6d20: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6d30: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6d40: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6d50: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6d60: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6d70: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6d80: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6d90: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6da0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6db0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6dc0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6dd0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6de0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6df0: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6e00: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6e10: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6e20: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6e30: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6e40: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6e50: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6e60: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6e70: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6e80: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6e90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6ea0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6eb0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6ec0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ed0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ef0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6f00: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f10: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6f30: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6f40: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6f60: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6f70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6f80: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6f90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6fa0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6fb0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6fc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6fd0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6fe0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ff0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7020: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7030: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7040: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7050: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7070: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7080: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7090: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
70a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
70b0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
70c0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
70d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
70e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
70f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7100: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7110: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7120: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7130: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7150: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7160: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7170: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7180: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7190: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
71a0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
71b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
71c0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
71d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
71e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
71f0: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7200: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7210: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7220: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7230: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7240: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7250: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7260: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7270: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7280: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
7290: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
72a0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
72b0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
72c0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
72d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
72e0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
72f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7300: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7310: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7320: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7340: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7350: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7360: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7370: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7380: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7390: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
73a0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
73b0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
73c0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
73d0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
73e0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
73f0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7410: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7420: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7430: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7440: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7450: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7460: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7470: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7480: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
7490: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
74a0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
74b0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
74c0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
74d0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
74e0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
74f0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7500: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7510: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7520: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7530: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7540: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7550: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7560: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7570: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7580: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7590: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
75a0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
75b0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
75c0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
75d0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
75e0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
75f0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7600: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7610: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7620: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7630: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7640: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7650: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7660: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7670: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7680: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7690: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
76a0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
76b0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
76c0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
76d0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
76e0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
76f0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7700: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7710: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7720: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7730: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7740: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7750: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7760: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7770: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7780: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7790: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
77a0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
77b0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
77c0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
77d0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
77e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
77f0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7800: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7810: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7820: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7830: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7840: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7850: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7860: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7870: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7880: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7890: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
78a0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
78b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
78d0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
78e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
78f0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7900: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7910: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7920: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7930: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7940: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7950: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7960: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7970: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7980: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7990: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
79a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
79b0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
79c0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
79d0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
79e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
79f0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7a00: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7a10: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7a20: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7a30: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7a40: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7a50: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7a60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7a70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7a80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7a90: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7aa0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7ab0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7ac0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7ad0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7ae0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7af0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7b00: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7b10: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7b20: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7b40: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7b50: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7b60: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7b70: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7b80: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7b90: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7ba0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7bb0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7bc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bd0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7be0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c00: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7c10: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7c20: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7c30: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7c40: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7c50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7c60: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7c70: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7c80: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7c90: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7ca0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7cb0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7cc0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7cd0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7ce0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7cf0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7d00: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7d10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7d20: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7d30: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7d40: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7d50: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7d60: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7d70: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7d80: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7d90: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7da0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7db0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7dc0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7dd0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7de0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7df0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7e00: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7e10: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7e20: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7e30: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7e40: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e50: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7e60: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7e70: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7e80: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7e90: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7ea0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7eb0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7ec0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ed0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7ee0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7ef0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7f00: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7f10: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7f20: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7f30: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7f40: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7f50: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7f60: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7f70: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7f80: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7f90: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
7fa0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
7fb0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
7fc0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
7fd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7fe0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7ff0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8000: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8010: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8020: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8030: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8040: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8060: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8070: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8080: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
8090: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
80a0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
80b0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
80c0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
80d0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
80e0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
80f0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8100: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8110: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8120: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8130: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8140: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8150: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8160: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8170: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8180: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
8190: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
81a0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
81b0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
81c0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
81d0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
81e0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
81f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8200: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8210: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8220: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8230: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8240: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8250: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8260: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8270: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8280: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8290: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
82a0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
82b0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
82c0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
82d0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
82e0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
82f0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8300: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8310: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8320: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8330: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8340: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8350: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8360: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8370: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8380: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
8390: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
83a0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
83b0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
83c0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
83d0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
83e0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
83f0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8400: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8410: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8420: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8430: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8440: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8450: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8460: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8470: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8480: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
8490: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
84a0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
84b0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
84c0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
84d0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
84e0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
84f0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8500: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8510: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8520: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8530: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8540: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8550: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8560: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8570: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8580: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
8590: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
85a0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
85b0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
85c0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
85d0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
85e0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
85f0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8600: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8610: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8620: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8630: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8640: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8650: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8660: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8670: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8680: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8690: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
86a0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
86b0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
86c0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
86d0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
86e0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
86f0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8700: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8710: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8720: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8730: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8740: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8750: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8770: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8780: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8790: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
87a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87b0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87d0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8800: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8810: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8820: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8830: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8850: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8860: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8870: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8880: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8890: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
88a0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
88b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
88c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
88d0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
88f0: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8900: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8910: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8920: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8940: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8950: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8960: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8970: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8980: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8990: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
89a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
89b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
89c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
89d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
89e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
89f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8a00: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8a10: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8a20: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8a40: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8a50: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8a60: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8a70: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8a80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8a90: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8aa0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8ab0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8ac0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8ad0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8ae0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8af0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8b00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8b10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8b20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8b30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8b40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8b50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8b60: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8b70: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8b80: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8b90: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8ba0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8bb0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8bc0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8bd0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8be0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8bf0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c00: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8c10: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8c20: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8c30: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8c40: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8c50: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8c60: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8c70: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8c80: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8c90: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8ca0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8cb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8cc0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8cd0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8ce0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8cf0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8d00: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8d10: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8d20: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8d30: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8d40: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8d50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8d60: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8d70: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8d80: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8d90: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8da0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8db0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8dc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8dd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8de0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8df0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8e00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8e10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8e20: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8e30: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8e40: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8e50: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8e60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8e70: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8e80: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8e90: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8ea0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8eb0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ed0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8ee0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8ef0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8f00: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f10: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8f20: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8f30: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8f40: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8f50: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8f60: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8f70: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8f80: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8f90: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8fa0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8fb0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8fc0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8fd0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8fe0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8ff0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9000: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9010: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9020: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9030: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9040: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9050: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9060: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9070: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9080: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
9090: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
90a0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
90b0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
90c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
90d0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
90e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
90f0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9100: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9110: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9120: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9130: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9140: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9150: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9160: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9170: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9180: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
9190: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
91a0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
91b0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
91c0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
91d0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
91e0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
91f0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9200: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9210: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9220: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9230: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9240: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9260: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9270: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9280: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9290: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
92b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
92c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
92d0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
92e0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
92f0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9300: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9310: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9320: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9330: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9340: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9350: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9360: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9370: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9380: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
9390: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
93a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
93b0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
93c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
93d0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
93e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
93f0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9400: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9410: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9420: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9430: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9440: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9450: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9460: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9470: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9480: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9490: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
94a0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
94b0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
94c0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
94d0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
94e0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
94f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9500: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9510: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9520: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9530: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9540: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9550: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9560: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9570: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9580: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9590: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
95a0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
95b0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
95c0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
95d0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
95e0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
95f0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9600: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9610: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9620: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9630: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9650: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9660: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9670: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9680: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9690: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
96a0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
96b0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
96c0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
96d0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
96e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
96f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9700: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9710: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9720: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9730: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9740: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9750: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9760: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9770: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9780: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9790: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
97a0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
97b0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
97c0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
97d0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
97e0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
97f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9800: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9810: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9820: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9830: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9840: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9850: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9860: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9870: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9880: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9890: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
98a0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
98b0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
98c0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
98d0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
98e0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
98f0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9900: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9910: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9920: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9930: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9940: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9950: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9960: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9970: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9980: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9990: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
99a0: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
99b0: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
99c0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
99d0: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
99e0: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
99f0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9a00: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9a10: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9a20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9a30: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9a40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9a50: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9a60: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9a70: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9a80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a90: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9aa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9ab0: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9ac0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9ad0: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9ae0: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9af0: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9b00: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9b10: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9b20: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9b30: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9b40: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9b50: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9b60: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9b70: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9b80: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9b90: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9ba0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9bb0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9bc0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9bd0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9be0: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9bf0: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9c00: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9c10: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9c20: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9c30: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9c40: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9c50: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9c60: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9c70: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9c80: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9c90: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9ca0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9cb0: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9cc0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9cd0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9ce0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9cf0: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9d00: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9d10: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9d20: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9d30: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9d40: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9d50: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9d60: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9d70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9d80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9d90: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9da0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9db0: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9dc0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9dd0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9de0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9df0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9e00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e10: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9e20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9e30: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9e40: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9e50: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9e60: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9e70: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9e80: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9e90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9ea0: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9eb0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9ec0: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9ed0: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9ee0: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9ef0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9f00: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9f10: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9f20: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9f30: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9f40: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9f50: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9f60: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9f70: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9f80: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9f90: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9fa0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9fb0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9fc0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9fd0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fe0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9ff0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
a000: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a010: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
a020: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a030: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
a040: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
a050: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
a060: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
a070: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
a080: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
a090: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
a0a0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a0b0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
a0c0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
a0d0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
a0e0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
a0f0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
a100: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
a110: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
a120: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
a130: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
a140: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
a150: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
a160: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
a170: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
a180: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
a190: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
a1a0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
a1b0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
a1c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a1d0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
a1e0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
a1f0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
a200: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
a210: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
a220: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
a230: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
a240: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
a250: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
a260: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
a270: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a280: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
a290: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a2a0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
a2b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
a2c0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
a2d0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
a2e0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
a2f0: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
a300: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
a310: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
a320: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
a330: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
a340: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
a350: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
a360: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
a370: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
a380: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
a390: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
a3a0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
a3b0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
a3c0: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
a3d0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a3e0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a3f0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a400: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a410: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a440: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a450: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a460: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a470: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a480: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a490: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a4a0: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a4b0: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a4c0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a4d0: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a4e0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a4f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a500: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a510: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a520: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a530: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a540: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a550: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a560: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a570: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a580: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a590: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a5a0: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a5b0: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a5c0: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a5d0: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a5e0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a5f0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a600: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a610: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a620: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a630: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a640: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a650: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a660: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a670: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a680: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a690: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a6a0: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a6b0: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a6c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a6d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a6e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a6f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a700: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a710: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a720: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a730: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a740: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a750: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a760: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a770: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a780: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a790: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a7a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a7b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a7c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a7d0: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a7e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a800: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a810: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a820: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a830: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a840: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a850: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a860: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a870: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a880: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a890: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a8a0: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a8b0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a8c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a8d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a8e0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a8f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a900: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a910: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a920: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a930: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a940: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a950: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a960: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a970: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a980: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a990: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a9a0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a9b0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a9c0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a9d0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a9e0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a9f0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
aa00: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
aa10: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
aa20: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
aa30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
aa40: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aa50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aa60: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
aa70: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
aa80: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
aa90: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
aaa0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
aab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
aac0: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
aad0: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
aae0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
aaf0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
ab00: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
ab10: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
ab20: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
ab30: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
ab40: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
ab50: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
ab60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab70: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
ab80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ab90: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
aba0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
abb0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
abc0: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
abd0: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
abe0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
abf0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
ac00: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
ac10: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
ac20: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
ac30: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ac40: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ac50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ac60: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
ac70: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
ac80: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
ac90: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
aca0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
acb0: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
acc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
acd0: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
ace0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
acf0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
ad00: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
ad10: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
ad20: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
ad30: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
ad40: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
ad50: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
ad60: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
ad70: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
ad80: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
ad90: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
ada0: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
adb0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
adc0: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
add0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
ade0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
adf0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
ae00: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
ae10: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
ae20: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
ae30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ae40: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
ae50: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ae60: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
ae70: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
ae80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
ae90: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
aea0: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
aeb0: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
aec0: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
aed0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
aee0: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
aef0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af00: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
af10: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
af20: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
af30: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
af40: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
af50: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
af60: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
af70: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
af80: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
af90: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
afa0: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
afb0: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
afc0: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
afd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
afe0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aff0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
b000: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
b010: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
b020: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
b030: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
b040: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
b050: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
b060: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b070: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
b080: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
b090: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
b0a0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
b0b0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
b0c0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
b0d0: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
b0e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b0f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
b100: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
b110: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
b120: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
b130: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
b140: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
b150: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
b160: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
b170: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
b180: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
b190: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
b1a0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
b1b0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
b1c0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
b1d0: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
b1e0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
b1f0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b200: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
b210: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
b220: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
b230: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
b240: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
b250: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
b260: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b270: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
b280: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
b290: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
b2a0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
b2b0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
b2c0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
b2d0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
b2e0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
b2f0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
b300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b310: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b320: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b330: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
b340: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
b350: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
b360: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
b370: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b380: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b390: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b3a0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
b3b0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
b3c0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
b3d0: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b3e0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b3f0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b400: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b410: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b420: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b430: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b440: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b450: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b460: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b470: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b480: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b490: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b4a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b4b0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b4c0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b4d0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b4e0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b4f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b500: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b510: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b520: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b530: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b540: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b550: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b560: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b570: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b580: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b590: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5a0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b5b0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b5c0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b5d0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b5e0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b5f0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b600: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b610: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b620: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b630: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b640: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b650: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b660: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b670: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b680: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b690: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b6a0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b6b0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b6c0: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b6d0: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b6e0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b6f0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b700: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b710: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b720: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b730: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b740: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b750: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b760: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b770: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b780: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b790: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b7a0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b7b0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b7c0: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b7d0: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b7e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b7f0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b800: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b810: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b820: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b830: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b840: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b850: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b860: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b870: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b880: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b890: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b8a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b8b0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b8c0: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b8d0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b8e0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b8f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b900: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b910: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b920: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b930: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b940: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b950: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b960: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b970: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b980: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b990: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b9a0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b9b0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b9c0: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b9d0: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b9e0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b9f0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ba00: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ba10: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
ba20: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
ba30: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
ba40: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
ba50: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
ba60: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
ba70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ba80: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
ba90: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
baa0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
bab0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
bac0: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
bad0: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
bb00: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bb10: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
bb20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bb30: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
bb40: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
bb50: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
bb60: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
bb70: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
bb80: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
bb90: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bba0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bbb0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
bbc0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
bbd0: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
bbe0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
bbf0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
bc00: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
bc10: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
bc20: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
bc30: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
bc40: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
bc50: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
bc60: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
bc70: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
bc80: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
bc90: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
bca0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
bcb0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
bcc0: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
bcd0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
bce0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
bcf0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
bd00: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
bd10: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
bd20: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
bd30: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
bd40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bd50: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
bd60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bd70: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
bd80: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
bd90: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
bda0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
bdb0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
bdc0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
bdd0: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
bde0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
bdf0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be00: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
be10: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
be20: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
be30: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
be40: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
be50: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
be60: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
be70: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
be80: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
be90: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bea0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
beb0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bec0: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
bed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bee0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bef0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf00: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf10: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bf20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bf30: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bf40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bf50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bf60: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bf70: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
bf80: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
bf90: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
bfa0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
bfb0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
bfc0: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
bfd0: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
bfe0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bff0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
c000: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
c010: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c020: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c030: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c040: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c050: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
c060: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
c070: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
c080: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
c090: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c0a0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
c0b0: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
c0c0: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
c0d0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c0e0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c0f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c100: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c110: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
c120: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
c130: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
c140: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c150: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c160: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c170: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c180: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
c190: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
c1a0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
c1b0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
c1c0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
c1d0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
c1e0: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
c1f0: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
c200: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
c210: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
c220: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
c230: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
c240: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
c250: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
c260: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
c270: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
c280: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c290: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c2a0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c2b0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c2c0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c2d0: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
c2e0: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
c2f0: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
c300: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
c310: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
c320: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
c330: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
c340: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
c350: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
c360: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
c370: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
c380: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
c390: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
c3a0: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
c3b0: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
c3c0: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
c3d0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c3e0: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c3f0: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c400: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c410: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c420: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c430: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c440: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c450: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c460: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c470: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c480: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c490: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c4a0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c4b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c4c0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c4d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c4e0: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c4f0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c500: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c510: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c520: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c530: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c540: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c550: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c560: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c570: 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  pcode.  .**.** <
c580: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c590: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c5a0: 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65  RITE]].** If the
c5b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c5c0: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c5d0: 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e  E] opcode return
c5e0: 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65  s SQLITE_OK, the
c5f0: 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65  n.** the file de
c600: 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63  scriptor is plac
c610: 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69  ed in "batch wri
c620: 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a  te mode", which.
c630: 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62  ** means all sub
c640: 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70  sequent write op
c650: 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  erations will be
c660: 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f   deferred and do
c670: 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79  ne.** atomically
c680: 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51   at the next [SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c6a0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  T_ATOMIC_WRITE].
c6b0: 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61    Systems.** tha
c6c0: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  t do not support
c6d0: 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72   batch atomic wr
c6e0: 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e  ites will return
c6f0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c700: 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20  ..** ^Following 
c710: 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c  a successful SQL
c720: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64  ATOMIC_WRITE and
c740: 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65   prior to.** the
c750: 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45   closing [SQLITE
c760: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c770: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a  OMIC_WRITE] or.*
c780: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c790: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c7a0: 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77  WRITE], SQLite w
c7b0: 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56  ill make.** no V
c7c0: 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  FS interface cal
c7d0: 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ls on the same [
c7e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69  sqlite3_file] fi
c7f0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a  le descriptor.**
c800: 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c   except for call
c810: 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20  s to the xWrite 
c820: 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78  method and the x
c830: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
c840: 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49  od.** with [SQLI
c850: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c860: 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  NT]..**.** <li>[
c870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c880: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c890: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c8a0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c8b0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c8c0: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
c8d0: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
c8e0: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
c8f0: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
c900: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
c910: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c920: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c930: 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  to be performed 
c940: 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54  atomically..** T
c950: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c960: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
c970: 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK] if and only
c980: 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77   if the writes w
c990: 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f  ere.** all perfo
c9a0: 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  rmed successfull
c9b0: 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20  y and have been 
c9c0: 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72  committed to per
c9d0: 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e  sistent storage.
c9e0: 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
c9f0: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
ca00: 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  t it is successf
ca10: 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f  ul, this file co
ca20: 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74  ntrol takes.** t
ca30: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
ca40: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
ca50: 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68  write mode so th
ca60: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
ca70: 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  t.** write opera
ca80: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
ca90: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
caa0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cab0: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cac0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cad0: 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20  RITE without.** 
cae0: 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
caf0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49  ul call to [SQLI
cb00: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cb10: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a  TOMIC_WRITE]..**
cb20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cb30: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cb40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cb50: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cb60: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cb70: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
cb80: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
cb90: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
cba0: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
cbb0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
cbc0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cbe0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
cbf0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  be rolled back..
cc00: 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f  ** ^This file co
cc10: 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20  ntrol takes the 
cc20: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
cc30: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
cc40: 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68  te mode.** so th
cc50: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
cc60: 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t write operatio
cc70: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
cc80: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
cc90: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cca0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
ccb0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ccc0: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
ccd0: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cce0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
ccf0: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd00: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 20  OMIC_WRITE]..** 
cd10: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
cd20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
cd30: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
cd40: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
cd50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
cd60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
cd70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
cd80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
cd90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
cda0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
cdb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
cdc0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
cdd0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
cde0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
cdf0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
ce00: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
ce10: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
ce20: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
ce30: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
ce50: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
ce60: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
ce70: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
ce80: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
ce90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cea0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
ceb0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
cec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ced0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
cee0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
cef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cf00: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
cf10: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
cf20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cf30: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
cf40: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
cf50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cf60: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
cf70: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
cf80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf90: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
cfa0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
cfb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cfc0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
cfd0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
cfe0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
cff0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
d000: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
d010: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
d020: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
d030: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
d040: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
d050: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
d060: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
d070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
d080: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
d090: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
d0a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
d0b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d0c0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
d0d0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
d0e0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
d0f0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
d100: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
d110: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
d120: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
d130: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
d140: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
d150: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d160: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
d180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d190: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
d1a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
d1b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d1c0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
d1d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
d1e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d1f0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
d200: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64  TER        28.#d
d210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d220: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
d230: 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65  DLE       29.#de
d240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d250: 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20  L_PDB           
d260: 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66           30.#def
d270: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d280: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
d290: 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69  ITE     31.#defi
d2a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d2b0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
d2c0: 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  ITE    32.#defin
d2d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
d2e0: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
d2f0: 52 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70  RITE  33../* dep
d300: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
d310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d320: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
d330: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d340: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
d350: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d360: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
d370: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
d380: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
d390: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
d3a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
d3b0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
d3c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
d3d0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
d3e0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
d3f0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
d400: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
d410: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
d420: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
d430: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
d440: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
d450: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
d460: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
d470: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
d480: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
d490: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
d4a0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
d4b0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
d4c0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
d4d0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
d4e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d4f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
d500: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
d510: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
d520: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
d530: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d540: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
d550: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
d560: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d570: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
d580: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
d590: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
d5a0: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
d5b0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
d5c0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
d5d0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
d5e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
d5f0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
d600: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
d610: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
d620: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
d630: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
d640: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
d650: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
d660: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
d670: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
d680: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d690: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d6a0: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d6b0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
d6c0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
d6d0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
d6e0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d6f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d700: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
d710: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
d720: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
d730: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
d740: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
d750: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
d760: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
d770: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
d780: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
d790: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
d7a0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
d7b0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
d7c0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
d7d0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
d7e0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
d7f0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69   VFS interface i
d800: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65  s sometimes exte
d810: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e  nded by adding n
d820: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a  ew methods onto.
d830: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63  ** the end.  Eac
d840: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65  h time such an e
d850: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c  xtension occurs,
d860: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d870: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d  eld.** is increm
d880: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72  ented.  The iVer
d890: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74  sion value start
d8a0: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a  ed out as 1 in.*
d8b0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  * SQLite [versio
d8c0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74  n 3.5.0] on [dat
d8d0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e  eof:3.5.0], then
d8e0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a   increased to 2.
d8f0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b  ** with SQLite [
d900: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f  version 3.7.0] o
d910: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d  n [dateof:3.7.0]
d920: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65  , and then incre
d930: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74  ased.** to 3 wit
d940: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  h SQLite [versio
d950: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74  n 3.7.6] on [dat
d960: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64  eof:3.7.6].  Add
d970: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
d980: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  * may be appende
d990: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  d to the sqlite3
d9a0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20  _vfs object and 
d9b0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
d9c0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61  ue.** may increa
d9d0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75  se again in futu
d9e0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
d9f0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  QLite..** Note t
da00: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
da10: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
da20: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
da30: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
da40: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  ansition from.**
da50: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
da60: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73   3.5.9] to [vers
da70: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64  ion 3.6.0] on [d
da80: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20  ateof:3.6.0].** 
da90: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
daa0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
dab0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ot modified..**.
dac0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
dad0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
dae0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
daf0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
db00: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
db10: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
db20: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
db30: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
db40: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
db50: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
db60: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
db70: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
db80: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
db90: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
dba0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
dbb0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dbc0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
dbd0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
dbe0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
dbf0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
dc00: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
dc10: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
dc20: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
dc30: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
dc40: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
dc50: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
dc60: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
dc70: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
dc80: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
dc90: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
dca0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
dcb0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
dcc0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
dcd0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
dce0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
dcf0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
dd00: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
dd10: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
dd20: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
dd30: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
dd40: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
dd50: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
dd60: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
dd70: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
dd80: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
dd90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
dda0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
ddb0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
ddc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ddd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
dde0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
ddf0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
de00: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
de10: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
de20: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
de30: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
de40: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
de50: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
de60: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
de70: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
de80: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
de90: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
dea0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
deb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
dec0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
ded0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
dee0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
def0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
df00: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
df10: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
df20: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
df30: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
df40: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
df50: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
df60: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
df70: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
df80: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
df90: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
dfa0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
dfb0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
dfc0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
dfd0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
dfe0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
dff0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e000: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e010: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e020: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e030: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e040: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e050: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e060: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e070: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e080: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e090: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e0a0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e0b0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e0c0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e0d0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e0e0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e0f0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e100: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e110: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e120: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e130: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e140: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e150: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e160: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e170: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e180: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e190: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e1a0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e1b0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e1c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e1d0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e1e0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
e1f0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
e200: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
e210: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
e220: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
e230: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e240: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
e250: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
e260: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
e270: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
e280: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
e290: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
e2a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
e2b0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
e2c0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
e2d0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
e2e0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
e2f0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
e300: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
e310: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
e320: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
e330: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
e340: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
e350: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
e360: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
e370: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
e380: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
e390: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
e3a0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
e3b0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
e3c0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
e3d0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e3e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e3f0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
e400: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e410: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
e420: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e430: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
e440: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e450: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
e460: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e470: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
e480: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
e4a0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e4b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
e4c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
e4d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e4e0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
e4f0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
e500: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
e510: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
e520: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
e530: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
e540: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
e550: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
e560: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
e570: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
e580: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
e590: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
e5a0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
e5b0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
e5c0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
e5d0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
e5e0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
e5f0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
e600: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
e610: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
e620: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
e630: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
e640: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
e650: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
e660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e670: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
e680: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
e690: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
e6a0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
e6b0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
e6c0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
e6d0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
e6e0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
e6f0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
e700: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
e710: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
e720: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
e730: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
e740: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e750: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e760: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
e770: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
e790: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e7a0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
e7b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
e7c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e7d0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
e7e0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
e7f0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
e800: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
e810: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e820: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e830: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
e840: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
e850: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
e860: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
e870: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
e880: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
e890: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e8a0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e8b0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
e8c0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
e8d0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
e8e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e8f0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
e900: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
e910: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
e920: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
e930: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
e940: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
e950: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
e960: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
e970: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
e980: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
e990: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
e9a0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
e9b0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
e9c0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
e9d0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
e9e0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
e9f0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
ea00: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
ea10: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
ea20: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
ea30: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
ea40: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
ea50: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
ea60: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
ea70: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
ea80: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
ea90: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
eaa0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
eab0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
eac0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
ead0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
eae0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
eaf0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
eb00: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
eb10: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
eb20: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
eb30: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
eb40: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
eb50: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
eb60: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
eb70: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
eb80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
eb90: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
eba0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
ebb0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ebc0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
ebd0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
ebe0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
ebf0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
ec00: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
ec10: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
ec20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ec30: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
ec40: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
ec50: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
ec60: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
ec70: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
ec80: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
ec90: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
eca0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
ecb0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
ecc0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
ecd0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
ece0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
ecf0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
ed00: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
ed10: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
ed20: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
ed30: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ed40: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
ed50: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
ed60: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
ed70: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
ed80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
ed90: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
eda0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
edb0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
edc0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
edd0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
ede0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
edf0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
ee00: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
ee10: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
ee20: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
ee30: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
ee40: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
ee50: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
ee60: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ee70: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
ee80: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
ee90: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
eea0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
eeb0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
eec0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
eed0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
eee0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
eef0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
ef00: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
ef10: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
ef20: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
ef30: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
ef40: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
ef50: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
ef60: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
ef70: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
ef80: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
ef90: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
efa0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
efb0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
efc0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
efd0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
efe0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
eff0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f000: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f010: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f020: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f030: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f040: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f050: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f060: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f070: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f080: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f090: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f0a0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f0b0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f0c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f0d0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f0e0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f0f0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f100: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f110: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f120: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f130: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f140: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f150: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f160: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f170: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f180: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f190: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f1a0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f1b0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f1c0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f1d0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f1e0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
f1f0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
f200: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f210: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
f220: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
f230: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
f240: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
f250: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
f260: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
f270: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
f280: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
f290: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f2a0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
f2b0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f2c0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
f2d0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
f2e0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
f2f0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
f300: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
f310: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
f320: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
f330: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f340: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
f350: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
f360: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
f370: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
f380: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
f390: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
f3a0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
f3b0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
f3c0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
f3d0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
f3e0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
f3f0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
f400: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
f410: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
f420: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
f430: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
f440: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
f450: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
f460: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
f470: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
f480: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
f490: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
f4a0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
f4b0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
f4c0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
f4d0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
f4e0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
f4f0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
f500: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
f510: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
f520: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
f530: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
f540: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
f550: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
f560: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
f570: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
f580: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
f590: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
f5a0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
f5b0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
f5c0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
f5d0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
f5e0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
f5f0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
f600: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
f610: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
f620: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
f630: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
f640: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
f650: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f660: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
f670: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
f680: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
f690: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
f6a0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
f6b0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
f6c0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
f6d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f6e0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
f6f0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
f700: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f710: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
f720: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
f730: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
f740: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
f750: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
f760: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
f770: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
f780: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
f790: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
f7a0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
f7b0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
f7c0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f7d0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f7e0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f7f0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f800: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f810: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f820: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f830: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f840: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f850: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f860: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f870: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f880: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f890: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f8a0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f8b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f8c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f8d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f8e0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f8f0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f900: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
f910: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
f920: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
f930: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f940: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f950: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
f960: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
f970: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f980: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f990: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
f9a0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
f9b0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
f9c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f9d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f9e0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
f9f0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
fa00: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
fa10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fa20: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
fa30: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
fa40: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
fa50: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
fa60: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
fa70: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
fa80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
fa90: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
faa0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
fab0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
fac0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fad0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
fae0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
faf0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
fb00: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
fb10: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
fb20: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
fb30: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
fb40: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
fb50: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
fb60: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
fb70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
fb80: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
fb90: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
fba0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
fbb0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fbc0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fbd0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
fbe0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
fbf0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
fc00: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
fc10: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
fc20: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
fc30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
fc50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
fc60: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
fc70: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fc80: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fc90: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
fca0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
fcb0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fcc0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
fcd0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
fce0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
fcf0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
fd00: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fd10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fd20: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
fd30: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
fd40: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
fd50: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
fd60: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fd70: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fd80: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
fd90: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
fda0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fdb0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fdc0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fdd0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fde0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fdf0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
fe00: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
fe10: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fe20: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
fe30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
fe40: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
fe50: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
fe60: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
fe70: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
fe80: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
fe90: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
fea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
feb0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
fec0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
fed0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
fee0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
fef0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
ff00: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
ff10: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
ff20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
ff30: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
ff40: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
ff50: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
ff60: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
ff70: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ff80: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
ff90: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
ffa0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
ffb0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ffc0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
ffd0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
ffe0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
fff0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10000 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10010 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10020 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10030 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10040 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10050 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10060 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10070 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10080 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
10090 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
100a0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
100b0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
100c0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
100d0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
100e0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
100f0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
10100 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10110 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10120 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10130 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10140 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10150 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10160 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10170 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10180 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10190 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
101a0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
101b0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
101c0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
101d0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
101e0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
101f0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
10200 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10210 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10220 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10240 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10250 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10260 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10270 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10280 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10290 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
102a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
102b0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
102c0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
102d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
102e0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
102f0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
10300 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10310 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10320 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10330 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10340 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10350 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10360 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10370 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10380 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10390 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
103a0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
103b0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
103c0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
103d0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
103e0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
103f0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10400 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10410 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10420 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10430 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10440 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10450 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10460 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10470 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10480 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10490 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
104a0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
104b0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
104c0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
104d0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
104e0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
104f0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
10500 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10510 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10530 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10540 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10550 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10560 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10570 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10580 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10590 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
105a0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
105b0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
105c0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
105d0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
105e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
105f0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10600 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10610 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10620 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10630 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10640 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10660 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10670 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10680 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10690 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
106a0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
106b0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
106c0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
106d0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
106e0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
106f0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
10700 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10710 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10720 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10730 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10740 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10760 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10770 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10780 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10790 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
107a0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
107b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
107c0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
107d0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
107e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
107f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
10800 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10810 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10820 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10830 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10840 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10850 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10860 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10870 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10880 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10890 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
108a0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
108b0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
108c0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
108d0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
108e0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
108f0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
10900 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10910 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10920 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10930 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10940 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10950 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10960 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10970 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10980 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10990 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
109a0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
109b0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
109c0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
109d0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
109e0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
109f0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10a00 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10a10 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10a20 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10a30 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10a40 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10a50 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10a60 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10a70 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10a80 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10a90 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10aa0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10ab0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ac0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10ad0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10ae0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10af0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10b00 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10b10 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10b20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10b30 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10b40 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10b50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10b60 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10b70 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10b80 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10b90 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10ba0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
10bb0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
10bc0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10bd0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10be0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
10bf0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
10c00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c10 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
10c20 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10c30 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
10c40 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10c50 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10c60 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
10c70 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
10c80 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
10c90 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
10ca0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
10cb0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
10cc0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10cd0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10ce0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
10cf0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
10d00 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
10d10 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
10d20 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
10d30 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10d40 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10d50 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10d60 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10d70 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
10d80 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
10d90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10da0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10db0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10dc0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10dd0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10de0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10df0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10e00 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10e10 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10e20 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10e30 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10e40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10e50 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10e60 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
10e70 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
10e80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
10e90 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10ea0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10eb0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10ec0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10ed0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10ee0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10ef0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10f00 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
10f10 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
10f20 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
10f30 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
10f40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10f50 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
10f60 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
10f70 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
10f80 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
10f90 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
10fa0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
10fb0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
10fc0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
10fd0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
10fe0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
10ff0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
11000 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11010 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11020 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11030 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11040 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11050 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11060 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11070 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11080 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
11090 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
110a0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
110b0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
110c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
110d0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
110e0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
110f0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
11100 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11110 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11120 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11130 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11140 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11150 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11160 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11170 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11180 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
11190 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
111a0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
111b0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
111c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
111d0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
111e0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
111f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11200 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11210 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11220 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11230 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11240 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11250 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11260 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11270 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11280 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11290 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
112a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
112b0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
112c0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
112d0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
112e0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
112f0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11300 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11310 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11320 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11330 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11340 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11350 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11360 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11370 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11380 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11390 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
113a0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
113b0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
113c0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
113d0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
113e0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
113f0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
11400 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11410 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11420 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11430 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11440 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11450 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11460 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11470 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11480 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11490 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
114a0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
114b0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
114c0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
114d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
114e0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
114f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
11500 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11510 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11520 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11530 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11540 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11550 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11560 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11570 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11580 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11590 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
115a0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
115b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
115c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
115d0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
115e0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
115f0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
11600 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11610 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11620 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11630 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11640 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11650 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11660 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11670 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11680 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11690 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
116a0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
116b0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
116c0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
116d0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
116e0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
116f0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
11700 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11710 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11720 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11730 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11740 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11750 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11760 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11770 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11780 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11790 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
117a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
117b0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
117c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
117d0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
117e0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
117f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
11800 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
11810 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11820 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
11830 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11840 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11850 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11860 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11870 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
11880 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11890 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
118a0 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
118b0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
118c0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
118d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
118e0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
118f0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
11900 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
11910 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
11920 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
11930 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
11940 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
11950 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
11960 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
11970 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
11980 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
11990 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
119a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
119b0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
119c0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
119d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
119e0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
119f0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
11a00 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
11a10 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
11a20 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
11a30 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
11a40 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
11a50 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
11a60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11a70 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
11a80 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11a90 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11aa0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11ab0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11ac0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11ad0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11ae0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11af0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11b00 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11b10 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11b20 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11b30 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11b40 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11b50 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11b60 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11b70 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11b80 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
11b90 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
11ba0 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11bb0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11bc0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
11bd0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
11be0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11bf0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
11c00 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
11c10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11c20 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11c30 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11c40 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
11c50 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
11c60 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
11c70 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
11c80 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
11c90 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
11ca0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11cb0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
11cc0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
11cd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ce0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
11cf0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
11d00 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
11d10 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11d20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
11d30 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
11d40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
11d50 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
11d60 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
11d70 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
11d80 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
11d90 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
11da0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
11db0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11dc0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
11dd0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11de0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11df0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11e00 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11e10 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
11e20 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
11e30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
11e40 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11e50 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11e60 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
11e70 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
11e80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11e90 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
11ea0 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
11eb0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
11ec0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
11ed0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
11ee0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
11ef0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
11f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
11f10 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
11f20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
11f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
11f40 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
11f50 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11f60 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
11f70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
11f80 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
11f90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
11fa0 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
11fb0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
11fc0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
11fd0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
11fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11ff0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
12000 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
12010 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
12020 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12030 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12040 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
12050 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
12060 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
12070 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
12080 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
12090 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
120a0 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
120b0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
120c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
120d0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
120e0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
120f0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12100 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12110 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12120 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12130 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12140 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12150 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12160 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12170 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12180 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12190 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
121a0 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
121b0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
121c0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
121d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
121e0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
121f0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
12200 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12210 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12220 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12230 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12240 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12250 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12260 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12270 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12280 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12290 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
122a0 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
122b0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
122c0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
122d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
122e0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
122f0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
12300 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
12310 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12320 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12330 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12340 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12350 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12360 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12370 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12380 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12390 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
123a0 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
123b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
123c0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
123d0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
123e0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
123f0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
12400 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12410 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12420 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12430 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12440 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12450 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12460 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12480 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12490 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
124a0 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
124b0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
124c0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
124d0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
124e0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
124f0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
12500 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
12510 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12520 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12530 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12540 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
12550 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
12560 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
12570 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
12580 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
12590 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
125a0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
125b0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
125c0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
125d0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
125e0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
125f0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12600 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
12610 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12620 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12630 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
12640 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
12650 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12660 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
12670 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
12680 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
12690 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
126a0 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
126b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
126c0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
126d0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
126e0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
126f0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
12700 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
12710 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
12720 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
12730 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
12740 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
12750 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
12760 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
12770 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
12780 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
12790 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
127a0 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
127b0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
127c0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
127d0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
127e0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
127f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
12800 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
12810 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
12820 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
12830 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
12840 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
12850 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
12860 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
12870 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
12880 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
12890 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
128a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
128b0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
128c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
128d0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
128e0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
128f0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
12900 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
12910 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
12920 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
12930 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
12940 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
12950 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
12960 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
12970 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
12980 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
12990 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
129a0 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
129b0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
129c0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
129d0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
129e0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
129f0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
12a00 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
12a10 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
12a20 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
12a30 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
12a40 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
12a50 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
12a60 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
12a70 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
12a80 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
12a90 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
12aa0 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
12ab0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12ac0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12ad0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
12ae0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
12af0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12b00 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
12b10 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
12b20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
12b30 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
12b40 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
12b50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
12b60 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12b70 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
12b80 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
12b90 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
12ba0 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
12bb0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
12bc0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
12bd0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12be0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
12bf0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
12c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12c10 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
12c20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12c30 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
12c40 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
12c50 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
12c60 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
12c70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
12c80 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
12c90 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
12ca0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12cb0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
12cc0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
12cd0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
12ce0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
12cf0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
12d00 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
12d10 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
12d20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
12d30 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
12d40 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
12d50 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
12d60 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
12d70 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
12d80 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
12d90 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
12da0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12db0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12dc0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12dd0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12de0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12df0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12e00 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12e10 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12e20 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12e30 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12e40 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12e50 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12e60 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
12e70 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
12e80 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
12e90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12ea0 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
12eb0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12ec0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12ed0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12ee0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12ef0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12f00 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
12f10 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
12f20 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
12f30 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
12f40 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
12f50 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
12f60 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
12f70 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
12f80 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
12f90 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
12fa0 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
12fb0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12fc0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
12fd0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
12fe0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
12ff0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
13000 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13010 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13020 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13030 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13040 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13050 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13060 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13070 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13080 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13090 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
130a0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
130b0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
130c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
130d0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
130e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
130f0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13100 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13110 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13120 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13130 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13140 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13150 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13160 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13170 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13180 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13190 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
131a0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
131b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
131c0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
131d0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
131e0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
131f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13200 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13210 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
13220 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
13230 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
13240 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
13250 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13260 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
13270 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13290 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
132a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
132b0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
132c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
132d0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
132e0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
132f0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13300 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13310 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13320 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
13330 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13340 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13350 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
13360 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
13370 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
13380 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
13390 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
133a0 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
133b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
133c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
133d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
133e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
133f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13400 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13410 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13420 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13430 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13440 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
13450 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
13460 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
13470 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
13480 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13490 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
134a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
134b0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
134c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
134d0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
134e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
134f0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13510 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13530 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13540 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13550 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13560 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13570 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13580 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13590 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
135a0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
135b0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
135c0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
135d0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
135e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
135f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13600 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13610 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13620 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
13630 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
13640 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
13650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13660 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13670 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
13680 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
13690 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
136a0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
136b0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
136c0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
136d0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
136e0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
136f0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
13700 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
13710 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
13720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13730 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13740 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
13750 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13760 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13770 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13780 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13790 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
137a0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
137b0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
137c0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
137d0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
137e0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
137f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13800 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
13810 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13820 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13830 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13840 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
13850 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13860 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13870 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13880 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
13890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
138a0 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
138b0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
138c0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
138d0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
138e0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
138f0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13900 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
13910 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
13920 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
13930 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
13940 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
13950 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
13960 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
13970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13980 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13990 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
139a0 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
139b0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
139c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
139d0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
139e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
139f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13a00 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
13a10 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
13a20 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
13a30 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
13a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
13a50 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
13a60 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
13a70 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
13a80 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
13a90 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
13aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ab0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
13ac0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
13ad0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
13ae0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
13af0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
13b00 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
13b10 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13b20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13b30 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13b40 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13b50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13b60 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
13b70 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
13b80 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
13b90 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
13ba0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
13bb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13bc0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
13bd0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13be0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13c00 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
13c10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13c20 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13c30 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13c40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13c50 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
13c60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13c80 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13c90 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13ca0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13cc0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13cd0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13ce0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13cf0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13d00 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
13d10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13d20 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
13d30 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
13d40 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
13d50 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
13d60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13d70 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13d80 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
13d90 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
13da0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
13db0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
13dc0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13dd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
13de0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
13df0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
13e00 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
13e10 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
13e20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13e30 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
13e40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13e50 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
13e60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13e80 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13e90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13ea0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13eb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13ec0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13ee0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13ef0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
13f00 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
13f10 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
13f20 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
13f30 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
13f40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13f50 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
13f60 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
13f70 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
13f80 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
13f90 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13fa0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
13fb0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
13fc0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
13fd0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13fe0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
13ff0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
14000 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14010 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14030 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  ALL_MALLOC]] <dt
14040 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14050 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  MALL_MALLOC</dt>
14060 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14080 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  L_MALLOC option 
14090 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
140a0 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65  ument of.** type
140b0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
140c0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
140d0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72  which if true pr
140e0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f  ovides a hint to
140f0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20  .** SQLite that 
14100 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20  it should avoid 
14110 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
14120 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73  ocations if poss
14130 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ible..** SQLite 
14140 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20  will run faster 
14150 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f  if it is free to
14160 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f   make large memo
14170 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a  ry allocations,.
14180 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c  ** but some appl
14190 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72  ication might pr
141a0 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77  efer to run slow
141b0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66  er in exchange f
141c0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  or.** guarantees
141d0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72   about memory fr
141e0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  agmentation that
141f0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66   are possible if
14200 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61   large.** alloca
14210 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65  tions are avoide
14220 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  d.  This hint is
14230 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a   normally off..*
14240 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14260 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14280 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14290 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
142a0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
142b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
142c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
142d0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
142e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
142f0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
14300 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14310 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14320 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14330 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14340 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14360 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14370 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14380 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14390 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
143a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
143b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
143c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
143d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
143e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
143f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14400 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14410 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14420 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14430 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14440 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
14450 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
14460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14470 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
14480 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
14490 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
144a0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
144b0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
144c0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
144d0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
144e0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
144f0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
14500 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
14510 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
14520 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14530 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
14540 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14550 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
14560 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14570 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
14580 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  option is no lon
14590 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  ger used..** </d
145a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
145b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
145c0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
145d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
145e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
145f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14600 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
14610 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
14620 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
14630 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
14640 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
14650 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
14660 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
14670 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14680 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
14690 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
146a0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
146b0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
146c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
146d0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
146e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
146f0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14710 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
14720 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14730 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14740 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14750 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
14760 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
14770 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
14780 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
14790 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
147a0 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
147b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
147c0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
147d0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
147e0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
147f0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
14800 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
14810 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
14820 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
14830 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
14840 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
14850 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14860 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14870 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
14880 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
14890 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
148a0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
148b0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
148c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
148d0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
148e0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
148f0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
14900 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
14910 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
14920 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
14930 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
14940 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
14950 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
14960 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
14970 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
14980 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14990 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
149a0 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
149b0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
149c0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
149d0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
149e0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
149f0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
14a00 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
14a10 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
14a20 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
14a30 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
14a40 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
14a50 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
14a60 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
14a70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
14a80 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
14a90 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
14aa0 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
14ab0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
14ac0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
14ad0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
14ae0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
14af0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
14b00 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
14b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14b20 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
14b30 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
14b40 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
14b50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
14b60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14b70 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
14b80 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
14b90 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
14ba0 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
14bb0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
14bc0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
14bd0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
14be0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
14bf0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
14c00 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
14c10 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
14c20 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
14c30 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
14c40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14c50 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
14c60 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
14c70 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
14c80 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
14c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14ca0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14cb0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14cd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14ce0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
14cf0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14d00 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14d10 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14d20 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14d30 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14d40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14d50 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14d60 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14d70 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14d80 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14d90 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
14da0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14db0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
14dc0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
14dd0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
14de0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14df0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14e00 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14e10 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14e20 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14e30 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14e40 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14e50 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14e60 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14e80 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14e90 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
14ea0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
14eb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
14ec0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
14ed0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14ee0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14ef0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14f00 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14f10 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14f20 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14f30 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
14f40 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
14f50 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
14f60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14f70 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
14f80 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
14f90 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
14fa0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
14fb0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14fd0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
14fe0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
14ff0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
15000 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
15010 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15020 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
15030 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
15040 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
15050 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15060 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
15070 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15080 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
15090 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
150a0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
150b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
150c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
150d0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
150e0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
150f0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
15100 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
15110 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
15120 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
15130 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
15140 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
15150 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
15160 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
15170 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15180 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
15190 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
151a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
151b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
151c0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
151d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
151e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
151f0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
15200 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15210 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15220 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15230 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
15240 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
15250 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15260 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
15270 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
15280 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
15290 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
152a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
152b0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
152c0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
152d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
152e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
152f0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15300 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
15310 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
15320 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
15330 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
15340 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15350 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15360 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15370 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15380 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15390 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
153a0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
153b0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
153c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
153d0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
153e0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
153f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15400 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
15410 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
15420 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15430 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15440 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15450 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15470 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15480 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15490 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
154a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
154b0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
154c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
154d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
154e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
154f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
15500 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15510 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15520 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
15530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
15540 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
15550 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
15560 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
15570 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
15580 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
15590 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
155a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
155b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
155c0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
155d0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
155e0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
155f0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
15600 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
15610 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
15620 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
15630 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
15640 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15650 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15660 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15670 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15680 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15690 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
156a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
156b0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
156c0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
156d0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
156e0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
156f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15700 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
15710 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15720 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
15730 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15740 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15760 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15770 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15780 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
15790 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
157a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
157b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
157c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
157d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
157e0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
157f0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
15800 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
15810 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
15820 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
15830 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15850 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15860 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15870 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
15880 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
15890 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
158a0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
158b0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
158c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
158d0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
158e0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
158f0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
15900 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
15910 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
15920 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15930 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
15940 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
15950 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
15960 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
15970 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
15980 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15990 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
159a0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
159b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
159c0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
159d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
159e0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
159f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15a10 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15a20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15a30 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
15a40 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
15a50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15a60 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15a70 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
15a80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
15a90 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
15aa0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
15ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15ac0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
15ad0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
15ae0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
15af0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15b00 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
15b10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15b20 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
15b30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15b40 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
15b50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15b60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b70 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
15b80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15b90 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
15ba0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15bb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15bc0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15bd0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
15be0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
15bf0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15c00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15c10 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15c20 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15c40 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15c50 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15c60 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15c70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15c80 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15c90 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
15ca0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
15cb0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
15cc0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15cd0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
15ce0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15cf0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15d00 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15d10 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15d20 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15d30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15d40 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15d50 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15d60 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15d70 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15d80 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15d90 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
15da0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
15db0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
15dc0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15dd0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
15de0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
15df0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15e00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15e10 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15e20 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15e30 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15e40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15e50 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15e60 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15e70 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15e80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15e90 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
15ea0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15eb0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15ec0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
15ed0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
15ee0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
15ef0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15f00 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15f10 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
15f20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15f30 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
15f40 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
15f50 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
15f60 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
15f70 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
15f80 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
15f90 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15fa0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
15fb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
15fc0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
15fd0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
15fe0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
15ff0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
16000 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
16010 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
16020 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
16030 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
16040 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
16050 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
16060 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
16070 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
16080 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
16090 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
160a0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
160b0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
160c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
160d0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
160e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
160f0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
16100 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16110 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
16120 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16130 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
16140 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16150 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
16160 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16170 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
16180 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
16190 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
161a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
161b0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
161c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
161d0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
161e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
161f0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
16200 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
16210 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
16220 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
16230 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
16240 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16250 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16260 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
16270 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
16280 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
16290 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
162a0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
162b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
162c0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
162d0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
162e0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
162f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
16300 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
16310 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
16320 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16330 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
16340 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
16350 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
16360 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
16370 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
16380 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
16390 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
163a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
163b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
163c0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
163d0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
163e0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
163f0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
16400 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
16410 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
16420 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
16430 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
16440 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
16450 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
16460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16470 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16480 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16490 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
164a0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
164b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
164c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
164d0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
164e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
164f0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
16500 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
16510 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
16520 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
16530 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16540 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
16550 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16560 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16570 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
16580 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
16590 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
165a0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
165b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
165c0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
165d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
165e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
165f0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
16600 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
16610 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
16620 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
16630 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
16640 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
16650 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
16660 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
16670 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
16680 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
16690 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
166a0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
166b0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
166c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
166d0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
166e0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
166f0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
16700 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
16710 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
16720 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
16730 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
16740 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
16750 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
16760 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
16770 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
16780 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
167a0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
167b0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
167c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
167d0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
167e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
167f0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
16800 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
16810 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
16820 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
16830 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
16840 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
16850 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
16860 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
16870 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
16880 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
16890 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
168a0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
168b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
168c0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
168d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
168e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
168f0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
16900 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
16910 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
16920 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
16930 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
16940 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16950 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
16960 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16970 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
16980 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
16990 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
169a0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
169b0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
169c0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
169d0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
169e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
169f0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
16a00 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
16a10 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
16a20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
16a30 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
16a40 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16a50 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
16a60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16a70 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
16a80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16a90 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
16aa0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16ab0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
16ac0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
16ad0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
16ae0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
16af0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
16b00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16b10 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
16b20 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
16b30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16b40 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
16b50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
16b60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
16b70 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
16b80 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
16b90 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
16ba0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
16bb0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
16bc0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
16bd0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
16be0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16bf0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16c00 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16c10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16c20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16c30 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16c40 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16c50 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16c60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16c70 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16c80 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16c90 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
16ca0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
16cb0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
16cc0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
16cd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16ce0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
16cf0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16d00 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16d10 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16d20 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16d30 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16d40 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16d50 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16d60 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16d70 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16d80 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16d90 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
16da0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
16db0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
16dc0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16dd0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
16de0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16df0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16e00 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16e20 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16e30 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16e40 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16e50 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16e60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16e70 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16e80 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16e90 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
16ea0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
16eb0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
16ec0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
16ed0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
16ee0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
16ef0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16f00 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
16f10 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
16f20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16f30 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
16f40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16f50 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
16f60 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
16f70 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
16f80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
16f90 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
16fa0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
16fb0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
16fc0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
16fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16fe0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
16ff0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17000 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17010 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
17020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17030 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
17040 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17050 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
17060 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
17070 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
17080 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
17090 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
170a0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
170b0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
170c0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
170d0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
170e0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
170f0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
17100 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
17110 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
17120 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
17130 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
17140 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17150 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
17160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17170 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
17180 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17190 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
171a0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
171b0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
171c0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
171d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
171e0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
171f0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
17200 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
17210 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
17220 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
17230 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
17240 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
17250 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
17260 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
17270 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
17280 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
17290 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
172a0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
172b0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
172c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
172d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
172e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
172f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17300 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
17310 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17320 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
17330 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17340 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
17350 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
17360 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
17370 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
17380 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
17390 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
173a0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
173b0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
173c0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
173d0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
173e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
173f0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
17400 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17410 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
17420 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
17430 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
17440 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
17450 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
17460 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
17470 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
17480 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
17490 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
174a0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
174b0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
174c0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
174d0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
174e0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
174f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
17500 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
17510 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
17520 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
17530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17540 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
17550 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17560 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17570 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17580 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17590 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
175a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
175b0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
175c0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
175d0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
175e0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
175f0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
17600 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
17610 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
17620 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
17630 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
17640 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
17650 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
17660 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
17670 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
17680 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
17690 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
176a0 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
176b0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
176c0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
176d0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
176e0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
176f0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
17700 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
17710 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
17720 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
17730 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
17740 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
17750 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
17760 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
17770 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
17780 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
17790 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
177a0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
177b0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
177c0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
177d0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
177e0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
177f0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
17800 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
17810 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
17820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
17830 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
17840 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17850 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17860 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
17870 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17880 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17890 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
178a0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
178b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
178c0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
178d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
178e0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
178f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17900 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
17910 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
17920 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17940 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
17950 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67     6  /* No long
17960 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
17970 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17980 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
17990 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
179a0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
179b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
179c0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
179d0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
179e0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
179f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a00 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
17a10 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
17a20 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
17a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17a40 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
17a50 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
17a60 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17a80 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
17a90 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
17aa0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
17ab0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
17ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
17ad0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
17ae0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
17af0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
17b00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
17b10 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
17b20 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
17b30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17b40 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
17b50 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17b60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17b70 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
17b80 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
17b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ba0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
17bb0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
17bc0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17bd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
17be0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
17bf0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
17c00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17c10 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
17c20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17c30 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17c50 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17c60 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17c70 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17c80 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17ca0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
17cb0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
17cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17cd0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
17ce0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
17cf0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
17d00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17d10 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
17d20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17d30 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17d40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17d50 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17d60 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17d70 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17d90 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17da0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
17db0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
17dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17dd0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
17de0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
17df0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
17e00 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
17e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17e20 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17e30 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17e50 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
17e60 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37  MALLOC        27
17e70 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
17e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17e90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
17ea0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
17eb0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
17ec0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
17ed0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
17ee0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
17ef0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17f00 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
17f10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
17f20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
17f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
17f40 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
17f50 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
17f60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17f70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
17f80 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
17f90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
17fa0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
17fb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17fc0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
17fd0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
17fe0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
17ff0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
18000 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
18010 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18020 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
18030 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
18040 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
18050 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18060 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
18070 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
18080 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
18090 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
180a0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
180b0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
180c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
180d0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
180e0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
180f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
18100 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
18110 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18120 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
18130 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18140 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
18150 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
18160 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
18170 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
18180 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
18190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
181a0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
181b0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
181c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
181d0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
181e0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
181f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
18200 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
18210 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
18220 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
18230 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
18240 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
18250 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18260 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
18270 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
18280 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
18290 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
182a0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
182b0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
182c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
182d0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
182e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
182f0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
18300 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18310 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
18320 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18330 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
18340 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
18350 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
18360 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18370 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
18380 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
18390 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
183a0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
183b0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
183c0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
183d0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
183e0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
183f0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
18400 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
18410 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
18420 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18430 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
18440 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
18450 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
18460 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
18470 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
18480 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
18490 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
184a0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
184b0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
184c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
184d0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
184e0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
184f0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
18500 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
18510 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
18520 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
18530 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
18540 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
18550 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
18560 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
18570 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
18580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18590 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
185a0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
185b0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
185c0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
185d0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
185e0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
185f0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
18600 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
18610 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
18620 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
18630 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
18640 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
18650 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18660 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18670 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
18680 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18690 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
186a0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
186b0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
186c0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
186d0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
186e0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
186f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18700 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
18710 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
18720 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
18730 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18740 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
18750 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18760 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
18770 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
18780 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
18790 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
187a0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
187b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
187c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
187d0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
187e0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
187f0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18800 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
18810 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
18820 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
18830 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18840 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18850 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18860 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18870 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18880 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18890 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
188a0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
188b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
188c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
188d0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
188e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
188f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18900 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18910 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
18920 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
18930 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18940 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18950 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18960 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18970 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18980 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18990 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
189a0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
189b0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
189c0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
189d0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
189e0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
189f0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18a00 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18a10 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
18a20 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
18a30 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
18a40 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18a50 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
18a60 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
18a70 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
18a80 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18a90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18aa0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18ab0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18ac0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18ad0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
18ae0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18af0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
18b00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18b10 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
18b20 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e  3_TOKENIZER</dt>
18b30 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18b40 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18b50 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18b60 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d  le the two-argum
18b70 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ent.** version o
18b80 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65  f the [fts3_toke
18b90 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  nizer()] functio
18ba0 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20  n which is part 
18bb0 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d  of the.** [FTS3]
18bc0 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
18bd0 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69  h engine extensi
18be0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  on..** There sho
18bf0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18c00 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18c10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
18c20 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
18c30 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
18c40 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f  to disable fts3_
18c50 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a  tokenizer() or.*
18c60 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18c70 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18c80 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76  zer() or negativ
18c90 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
18ca0 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
18cb0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
18cc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18cd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18ce0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18cf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18d00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18d10 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33  ate whether fts3
18d20 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69  _tokenizer is di
18d30 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
18d40 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
18d50 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18d60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18d70 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
18d80 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
18d90 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18da0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18db0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
18dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18dd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18de0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
18df0 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ION</dt>.** <dd>
18e00 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18e10 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18e20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b  or disable the [
18e30 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18e40 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74  ension()].** int
18e50 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65  erface independe
18e60 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61  ntly of the [loa
18e70 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
18e80 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
18e90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
18ea0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
18eb0 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65  on()] API enable
18ec0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f  s or disables bo
18ed0 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  th the.** C-API 
18ee0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
18ef0 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74  tension()] and t
18f00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18f10 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18f20 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  )]..** There sho
18f30 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18f40 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18f50 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72  .** When the fir
18f60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
18f70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
18f80 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68   1, then only th
18f90 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e  e C-API is.** en
18fa0 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51  abled and the SQ
18fb0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69  L function remai
18fc0 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66  ns disabled.  If
18fd0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18fe0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
18ff0 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
19000 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
19010 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
19020 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
19030 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
19040 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19050 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
19060 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
19070 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
19080 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
19090 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
190a0 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
190b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
190c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
190d0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
190e0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
190f0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19100 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
19110 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19120 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
19130 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
19140 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
19150 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19160 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19170 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
19180 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19190 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
191a0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
191b0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
191c0 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
191d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
191e0 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
191f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19200 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19210 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
19220 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61   name of the "ma
19230 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  in" database.** 
19240 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f  schema.  ^The so
19250 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  le argument is a
19260 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
19270 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69  nstant UTF8 stri
19280 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  ng.** which will
19290 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20   become the new 
192a0 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70  schema name in p
192b0 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20  lace of "main". 
192c0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73   ^SQLite.** does
192d0 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79   not make a copy
192e0 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e   of the new main
192f0 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72   schema name str
19300 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c  ing, so the appl
19310 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
19320 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
19330 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
19340 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46  into this DBCONF
19350 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63  IG option is unc
19360 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20  hanged.** until 
19370 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61  after the databa
19380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
19390 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  oses..** </dd>.*
193a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
193b0 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
193c0 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  _ON_CLOSE</dt>.*
193d0 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20  * <dd> Usually, 
193e0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
193f0 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63  in wal mode is c
19400 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65  losed or detache
19410 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74  d from a .** dat
19420 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51  abase handle, SQ
19430 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74  Lite checks if t
19440 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68  his will mean th
19450 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77  at there are now
19460 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69   no .** connecti
19470 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68  ons at all to th
19480 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73  e database. If s
19490 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61  o, it performs a
194a0 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20   checkpoint .** 
194b0 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65  operation before
194c0 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e   closing the con
194d0 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70  nection. This op
194e0 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64  tion may be used
194f0 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20   to.** override 
19500 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20  this behaviour. 
19510 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19520 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19530 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  is operation.** 
19540 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20  is an integer - 
19550 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61  non-zero to disa
19560 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  ble checkpoints-
19570 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72  on-close, or zer
19580 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  o (the.** defaul
19590 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65  t) to enable the
195a0 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  m. The second pa
195b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
195c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
195d0 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68  er.** into which
195e0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
195f0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19600 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e  hether checkpoin
19610 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68  ts-on-close.** h
19620 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65  ave been disable
19630 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72  d - 0 if they ar
19640 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  e not disabled, 
19650 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a  1 if they are..*
19660 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53  * </dd>.** <dt>S
19670 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19680 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
19690 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
196a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
196b0 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
196c0 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
196d0 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
196e0 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
196f0 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
19700 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
19710 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
19720 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
19730 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
19740 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
19750 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
19760 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
19770 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
19780 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
19790 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
197a0 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
197b0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
197c0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
197d0 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
197e0 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
197f0 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
19800 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
19810 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
19820 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
19830 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
19840 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
19850 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
19860 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
19870 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
19880 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
19890 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
198a0 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
198b0 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
198c0 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
198d0 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   lab..** </dd>.*
198e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
198f0 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
19900 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42  P</dt>.** <dd> B
19910 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f  y default, the o
19920 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e  utput of EXPLAIN
19930 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d   QUERY PLAN comm
19940 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a  ands does not .*
19950 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74  * include output
19960 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69   for any operati
19970 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ons performed by
19980 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19990 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f  s. This.** optio
199a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  n is used to set
199b0 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64   or clear (the d
199c0 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74  efault) a flag t
199d0 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73  hat governs this
199e0 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68  .** behavior. Th
199f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19a00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73  r passed to this
19a10 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
19a20 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f   integer -.** no
19a30 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65  n-zero to enable
19a40 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67   output for trig
19a50 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72  ger programs, or
19a60 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65   zero to disable
19a70 20 69 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f   it..** The seco
19a80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19a90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19aa0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19ab0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
19ac0 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
19ad0 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
19ae0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
19af0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
19b00 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
19b10 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
19b20 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
19b30 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ** </dd>.** </dl
19b40 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
19b50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
19b60 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20  NDBNAME         
19b70 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74     1000 /* const
19b80 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e   char* */.#defin
19b90 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19ba0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
19bb0 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20          1001 /* 
19bc0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
19bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19be0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19bf0 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31  FKEY           1
19c00 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  002 /* int int* 
19c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19c20 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19c30 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19c40 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74   1003 /* int int
19c50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19c60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c70 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
19c80 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69  ER 1004 /* int i
19c90 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
19ca0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19cb0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
19cc0 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74  SION 1005 /* int
19cd0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19ce0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19cf0 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53  _NO_CKPT_ON_CLOS
19d00 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69  E      1006 /* i
19d10 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19d20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19d30 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20  IG_ENABLE_QPSG  
19d40 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a           1007 /*
19d50 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19d70 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
19d80 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
19d90 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
19da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19db0 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20  CONFIG_MAX      
19dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30               100
19dd0 38 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43  8 /* Largest DBC
19de0 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ONFIG */../*.** 
19df0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
19e00 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
19e10 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
19e20 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
19e30 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
19e40 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19e50 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
19e60 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
19e70 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
19e80 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19e90 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
19ea0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
19eb0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
19ec0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
19ed0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19ee0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
19ef0 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
19f00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19f10 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
19f20 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
19f30 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
19f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
19f50 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
19f60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19f70 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
19f80 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
19f90 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
19fa0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
19fb0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
19fc0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
19fd0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
19fe0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
19ff0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
1a000 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
1a010 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
1a020 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
1a030 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
1a040 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
1a050 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
1a060 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
1a070 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
1a080 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
1a090 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1a0a0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
1a0b0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
1a0c0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
1a0d0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
1a0e0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
1a0f0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
1a100 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
1a110 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
1a120 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a130 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a140 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75  d(D) interface u
1a150 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  sually returns t
1a160 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a  he [rowid] of.**
1a170 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a180 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1a190 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
1a1a0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
1a1b0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
1a1c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a1d0 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73  tion D. ^Inserts
1a1e0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
1a1f0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
1a200 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64   not.** recorded
1a210 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  . ^If no success
1a220 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
1a230 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
1a240 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
1a250 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61  ed .** on the da
1a260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a270 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  n D, then sqlite
1a280 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a290 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a  wid(D) returns .
1a2a0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41  ** zero..**.** A
1a2b0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20  s well as being 
1a2c0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  set automaticall
1a2d0 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e  y as rows are in
1a2e0 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61  serted into data
1a2f0 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20  base.** tables, 
1a300 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a310 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1a320 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65  ion may be set e
1a330 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20  xplicitly by.** 
1a340 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73  [sqlite3_set_las
1a350 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a360 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72  ].**.** Some vir
1a370 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
1a380 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49  mentations may I
1a390 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20  NSERT rows into 
1a3a0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a  rowid tables as.
1a3b0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69  ** part of commi
1a3c0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  tting a transact
1a3d0 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75  ion (e.g. to flu
1a3e0 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61  sh data accumula
1a3f0 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  ted in memory.**
1a400 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68   to disk). In th
1a410 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65  is case subseque
1a420 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73  nt calls to this
1a430 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a440 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73   the rowid.** as
1a450 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1a460 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53  ese internal INS
1a470 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20  ERT operations, 
1a480 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a  which leads to .
1a490 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72  ** unintuitive r
1a4a0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20  esults. Virtual 
1a4b0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1a4c0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72  tions that do wr
1a4d0 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20  ite to rowid.** 
1a4e0 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77  tables in this w
1a4f0 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69  ay can avoid thi
1a500 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73  s problem by res
1a510 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  toring the origi
1a520 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61  nal .** rowid va
1a530 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  lue using [sqlit
1a540 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1a550 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f  rt_rowid()] befo
1a560 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a  re returning .**
1a570 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20   control to the 
1a580 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  user..**.** ^(If
1a590 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1a5a0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1a5b0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72  gger then this r
1a5c0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20  outine will .** 
1a5d0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
1a5e0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
1a5f0 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ed row as long a
1a600 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
1a610 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e   .** running. On
1a620 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ce the trigger p
1a630 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65  rogram ends, the
1a640 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a650 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
1a660 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
1a670 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
1a680 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61  e the trigger wa
1a690 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  s fired.)^.**.**
1a6a0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
1a6b0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
1a6c0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1a6d0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
1a6e0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
1a6f0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
1a700 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1a710 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a720 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1a730 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
1a740 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
1a750 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
1a760 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
1a770 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
1a780 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
1a790 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
1a7a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a7b0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
1a7c0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
1a7d0 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
1a7e0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a7f0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
1a800 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1a810 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
1a820 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
1a830 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
1a840 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
1a850 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
1a860 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
1a870 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
1a880 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
1a890 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1a8a0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
1a8b0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
1a8c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1a8d0 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
1a8e0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
1a8f0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
1a900 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
1a910 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
1a920 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
1a930 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
1a940 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
1a950 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
1a960 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
1a970 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
1a980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a990 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
1a9a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
1a9b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a9c0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a9d0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
1a9e0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
1a9f0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
1aa00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aa10 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
1aa20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1aa30 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
1aa40 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
1aa50 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
1aa60 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
1aa70 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
1aa80 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1aa90 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1aaa0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1aab0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
1aac0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1aad0 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
1aae0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
1aaf0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
1ab00 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
1ab10 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
1ab20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
1ab30 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1ab40 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1ab50 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
1ab60 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
1ab70 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
1ab80 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1ab90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1aba0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1abb0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
1abc0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
1abd0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
1abe0 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
1abf0 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
1ac00 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
1ac10 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
1ac20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
1ac30 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
1ac40 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
1ac50 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  se..*/.void sqli
1ac60 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1ac70 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
1ac80 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  3*,sqlite3_int64
1ac90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aca0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
1acb0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1acc0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1acd0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1ace0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1acf0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1ad00 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1ad10 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
1ad20 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
1ad30 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1ad40 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
1ad50 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1ad60 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
1ad70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1ad80 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
1ad90 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
1ada0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
1adb0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1adc0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1add0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
1ade0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
1adf0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
1ae00 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
1ae10 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
1ae20 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
1ae30 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
1ae40 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1ae50 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
1ae60 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
1ae70 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
1ae80 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
1ae90 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1aea0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
1aeb0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1aec0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
1aed0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1aee0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
1aef0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
1af00 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1af10 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1af20 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
1af30 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1af40 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
1af50 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
1af60 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
1af70 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
1af80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1af90 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
1afa0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
1afb0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
1afc0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1afd0 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
1afe0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
1aff0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1b000 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
1b010 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
1b020 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
1b030 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
1b040 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
1b050 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1b060 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
1b070 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
1b080 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
1b090 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
1b0a0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
1b0b0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
1b0c0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1b0d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
1b0e0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
1b0f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1b100 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
1b110 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
1b120 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
1b130 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
1b140 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
1b150 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
1b160 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
1b170 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b180 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
1b190 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b1a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
1b1b0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
1b1c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
1b1d0 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
1b1e0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
1b1f0 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
1b200 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
1b210 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
1b220 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1b230 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
1b240 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
1b250 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
1b260 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
1b270 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1b280 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b290 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
1b2a0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
1b2b0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
1b2c0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
1b2d0 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
1b2e0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
1b2f0 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
1b300 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
1b310 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
1b320 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1b330 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
1b340 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
1b350 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
1b360 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
1b370 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
1b380 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
1b390 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
1b3a0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
1b3b0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
1b3c0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
1b3d0 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
1b3e0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b3f0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b400 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1b410 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
1b420 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
1b430 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
1b440 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
1b450 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
1b460 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
1b470 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
1b480 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
1b490 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1b4a0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
1b4b0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
1b4c0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
1b4d0 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
1b4e0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1b4f0 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
1b500 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
1b510 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1b520 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1b530 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1b540 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1b550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
1b560 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
1b570 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1b580 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1b590 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1b5a0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1b5b0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b5c0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b5d0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b5e0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b5f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b600 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b610 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b620 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1b630 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1b640 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1b650 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1b660 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
1b670 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1b680 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1b6a0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1b6b0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
1b6c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b6d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1b6e0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1b6f0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1b700 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
1b710 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
1b720 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
1b730 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
1b740 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1b750 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
1b760 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
1b770 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b780 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
1b790 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
1b7a0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
1b7b0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
1b7c0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
1b7d0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1b7e0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1b7f0 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
1b800 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
1b810 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1b820 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b830 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
1b840 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
1b850 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
1b860 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
1b870 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
1b880 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
1b890 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
1b8a0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
1b8b0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1b8c0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
1b8d0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1b8e0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1b8f0 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
1b900 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
1b910 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1b920 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
1b930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1b940 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1b950 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1b960 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1b970 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1b980 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1b990 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1b9a0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1b9b0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1b9c0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1b9d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b9e0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1b9f0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1ba00 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1ba10 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1ba20 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1ba30 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1ba40 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1ba50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ba60 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1ba70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ba80 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1ba90 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1baa0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1bab0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1bac0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1bad0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1bae0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1baf0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1bb00 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1bb10 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1bb20 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1bb30 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1bb40 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1bb50 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1bb60 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1bb70 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1bb80 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1bb90 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1bba0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1bbb0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1bbc0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1bbd0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1bbe0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1bbf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1bc00 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1bc10 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1bc20 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1bc30 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1bc40 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1bc50 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1bc60 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1bc70 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1bc80 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1bc90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bca0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1bcb0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1bcc0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1bcd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1bce0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1bcf0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1bd00 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1bd10 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1bd20 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1bd30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bd40 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1bd50 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1bd60 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1bd70 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1bd80 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1bd90 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1bda0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1bdb0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1bdc0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1bdd0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1bde0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1bdf0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1be00 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1be10 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1be20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1be30 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1be40 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1be50 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1be60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1be70 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1be80 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1be90 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1bea0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1beb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1bec0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1bed0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1bee0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1bef0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1bf00 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1bf10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bf20 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1bf30 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1bf40 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bf50 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bf60 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1bf70 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1bf80 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1bf90 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1bfa0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1bfb0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1bfc0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1bfd0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1bfe0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1bff0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c000 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1c010 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1c020 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1c030 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1c040 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1c050 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1c060 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1c070 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1c080 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1c090 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1c0a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c0b0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1c0c0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1c0d0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1c0e0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1c0f0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1c100 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1c110 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1c120 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1c130 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1c140 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1c150 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69   returns..*/.voi
1c160 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1c170 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1c180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c190 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1c1a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1c1b0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1c1c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1c1d0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1c1e0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1c1f0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1c200 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1c210 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1c220 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1c230 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1c240 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1c250 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1c260 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1c270 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1c280 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1c290 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1c2a0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1c2b0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1c2c0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1c2d0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1c2e0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1c2f0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1c300 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1c310 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1c320 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1c330 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1c340 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1c350 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1c360 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1c370 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1c380 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1c390 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1c3a0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1c3b0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1c3c0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1c3d0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1c3e0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1c3f0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1c400 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1c410 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1c420 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1c430 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1c440 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1c450 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1c460 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1c470 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1c480 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1c490 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1c4a0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1c4b0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1c4c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c4d0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1c4e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1c4f0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1c500 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1c510 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1c520 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1c530 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c540 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c550 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1c560 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c570 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1c580 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1c590 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1c5a0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1c5b0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1c5c0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1c5d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1c5e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1c5f0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1c600 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1c610 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1c620 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c630 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1c640 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c650 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1c660 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1c670 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1c680 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1c690 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c6a0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1c6b0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1c6c0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1c6d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1c6e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1c6f0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1c700 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1c710 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c720 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1c730 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1c740 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1c750 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1c760 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1c770 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1c780 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1c790 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c7a0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1c7b0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1c7c0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
1c7d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c7e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1c7f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1c800 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1c810 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1c820 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1c830 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1c840 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1c850 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1c860 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1c870 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c880 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1c890 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c8a0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1c8b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c8c0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1c8d0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1c8e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1c8f0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c900 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1c910 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1c920 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c930 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1c940 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1c950 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c960 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c970 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1c980 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1c990 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1c9a0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1c9b0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1c9c0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c9d0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1c9e0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c9f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1ca00 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1ca10 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1ca20 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1ca30 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1ca40 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1ca50 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1ca60 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1ca70 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1ca80 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1ca90 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1caa0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1cab0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1cac0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1cad0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1cae0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1caf0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1cb00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1cb10 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1cb20 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1cb30 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1cb40 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1cb50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1cb60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1cb70 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1cb80 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1cb90 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1cba0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1cbb0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1cbc0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1cbd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1cbe0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1cbf0 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1cc00 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1cc10 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1cc20 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1cc30 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1cc40 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1cc50 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1cc60 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1cc70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1cc80 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1cc90 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1cca0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1ccb0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1ccc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1ccd0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1cce0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1ccf0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1cd00 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1cd10 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1cd20 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1cd30 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1cd40 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1cd50 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1cd60 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1cd70 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1cd80 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1cd90 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1cda0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1cdb0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1cdc0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1cdd0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1cde0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1cdf0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1ce00 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1ce10 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1ce20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1ce30 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1ce40 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1ce50 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1ce60 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1ce70 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1ce80 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1ce90 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1cea0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1ceb0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1cec0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1ced0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1cee0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1cef0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1cf00 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1cf10 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1cf20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1cf30 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1cf40 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1cf50 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1cf60 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1cf70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1cf80 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1cf90 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1cfa0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1cfb0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1cfc0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1cfd0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1cfe0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1cff0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1d000 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1d010 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1d020 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1d030 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1d040 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1d050 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1d060 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1d070 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1d080 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1d090 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1d0a0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1d0b0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1d0c0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1d0d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1d0e0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1d0f0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1d100 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1d110 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1d120 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1d130 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1d140 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d150 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1d160 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1d170 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1d180 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1d190 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1d1a0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1d1b0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1d1c0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1d1d0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1d1e0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1d1f0 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1d200 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1d210 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1d220 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1d230 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1d240 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1d250 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1d260 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1d270 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1d280 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1d290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1d2a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1d2b0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1d2c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1d2d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1d2e0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1d2f0 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1d300 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1d310 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1d320 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1d330 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1d340 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1d350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d360 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1d370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1d380 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1d390 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1d3a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1d3b0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1d3c0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  3*,int(*)(void*,
1d3d0 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  int),void*);../*
1d3e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1d3f0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1d400 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d410 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1d420 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1d430 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d440 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1d450 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1d460 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1d470 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1d480 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1d490 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1d4a0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1d4b0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1d4c0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1d4d0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d4e0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d4f0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1d500 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1d510 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1d520 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1d530 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1d540 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1d550 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1d560 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1d570 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1d580 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1d590 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1d5a0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1d5b0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1d5c0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1d5d0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1d5e0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1d5f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1d600 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1d610 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1d620 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1d630 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1d640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1d650 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1d660 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1d670 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1d680 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1d690 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d6a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1d6b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1d6c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1d6d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1d6e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1d6f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1d700 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1d710 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1d720 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1d730 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1d740 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1d750 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1d760 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1d770 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1d780 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1d790 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1d7a0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1d7b0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1d7c0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1d7d0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1d7e0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1d7f0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1d800 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1d810 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1d820 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1d830 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1d840 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1d850 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1d860 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d870 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1d880 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1d890 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1d8a0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1d8b0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1d8c0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1d8d0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1d8e0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1d8f0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1d900 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1d910 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1d920 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1d930 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1d940 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1d950 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1d960 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1d970 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1d980 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1d990 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1d9a0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1d9b0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1d9c0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1d9d0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1d9e0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1d9f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1da00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1da10 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1da20 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1da30 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1da40 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1da50 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1da60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1da70 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1da80 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1da90 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1daa0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1dab0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1dac0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1dad0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1dae0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1daf0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1db00 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1db10 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1db20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1db30 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1db40 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1db50 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1db60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1db70 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1db80 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1db90 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1dba0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1dbb0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1dbc0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1dbd0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1dbe0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1dbf0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1dc00 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1dc10 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1dc20 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1dc30 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1dc40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1dc50 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1dc60 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1dc70 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1dc80 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1dc90 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1dca0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dcb0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1dcc0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1dcd0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1dce0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dcf0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1dd00 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1dd10 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1dd20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1dd30 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1dd40 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1dd50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dd60 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1dd70 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1dd80 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1dd90 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1dda0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1ddb0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1ddc0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1ddd0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1dde0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1ddf0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1de00 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1de10 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1de20 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1de30 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1de40 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1de50 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1de60 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1de70 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1de80 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1de90 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1dea0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1deb0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dec0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1ded0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dee0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1def0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1df00 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1df10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1df20 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1df30 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1df40 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1df50 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1df60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1df70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1df80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1df90 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1dfa0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1dfb0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1dfc0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1dfd0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1dfe0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1dff0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1e000 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1e010 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1e020 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1e030 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1e040 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1e050 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1e060 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1e070 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1e080 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1e090 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1e0a0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1e0b0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1e0c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1e0d0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1e0e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1e0f0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1e100 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1e110 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1e120 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1e130 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1e140 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e150 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1e160 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e170 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1e180 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1e190 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1e1a0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1e1b0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1e1c0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1e1d0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1e1e0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1e1f0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1e200 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1e210 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1e220 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1e230 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1e240 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1e250 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1e260 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1e270 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1e280 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1e290 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1e2a0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1e2b0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1e2c0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1e2d0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1e2e0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1e2f0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1e300 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1e310 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1e320 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1e330 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1e340 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1e350 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1e360 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1e370 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1e380 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1e390 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1e3a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1e3b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1e3c0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1e3d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1e3e0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1e3f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1e400 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1e410 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1e420 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1e430 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1e440 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1e450 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1e460 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1e470 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1e480 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1e490 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e4a0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1e4b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1e4c0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1e4d0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1e4e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1e4f0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1e500 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1e510 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1e520 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1e530 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1e540 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1e550 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1e560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e570 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1e580 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1e590 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1e5a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1e5b0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1e5c0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1e5d0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1e5e0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1e5f0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1e600 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e610 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1e620 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1e630 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1e640 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1e650 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1e660 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1e670 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1e680 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1e690 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1e6a0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1e6b0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1e6c0 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1e6d0 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1e6e0 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1e6f0 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1e700 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1e710 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1e720 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1e730 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1e740 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1e750 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1e760 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1e770 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1e780 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1e790 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1e7a0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1e7b0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1e7c0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1e7d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e7e0 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1e7f0 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1e800 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1e810 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e820 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1e830 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1e840 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1e850 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1e860 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1e870 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1e880 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1e890 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1e8a0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1e8b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1e8c0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1e8d0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1e8e0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1e8f0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1e900 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e910 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1e920 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1e930 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1e940 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1e950 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1e960 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1e970 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1e980 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1e990 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1e9a0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1e9b0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1e9c0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1e9d0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1e9e0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e9f0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1ea00 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1ea10 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1ea20 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1ea30 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1ea40 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1ea50 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1ea60 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1ea70 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1ea80 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1ea90 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1eaa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1eab0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1eac0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1ead0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1eae0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1eaf0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1eb00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1eb10 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1eb20 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1eb30 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1eb40 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1eb50 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1eb60 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1eb70 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1eb80 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1eb90 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1eba0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1ebb0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1ebc0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1ebd0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1ebe0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1ebf0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1ec00 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1ec10 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1ec20 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1ec30 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1ec40 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1ec50 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1ec60 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1ec70 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1ec80 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1ec90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1eca0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1ecb0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1ecc0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1ecd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1ece0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ecf0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1ed00 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1ed10 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1ed20 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1ed30 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1ed40 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1ed50 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1ed60 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1ed70 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1ed80 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1ed90 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1eda0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1edb0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1edc0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1edd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1ede0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1edf0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1ee00 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1ee10 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1ee20 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1ee30 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1ee40 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1ee50 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1ee60 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1ee70 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1ee80 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1ee90 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1eea0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1eeb0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1eec0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1eed0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1eee0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1eef0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1ef00 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1ef10 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1ef20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1ef30 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1ef40 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1ef50 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1ef60 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ef70 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1ef80 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1ef90 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1efa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1efb0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1efc0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1efd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1efe0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1eff0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1f000 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1f010 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1f020 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1f030 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1f040 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1f050 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1f060 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1f070 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1f080 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1f090 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1f0a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1f0b0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1f0c0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1f0d0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1f0e0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1f0f0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1f100 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1f110 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1f120 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f130 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1f140 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1f150 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1f160 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1f170 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1f180 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1f190 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1f1a0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1f1b0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1f1c0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1f1d0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1f1e0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1f1f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1f200 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1f210 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1f220 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1f230 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1f240 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1f250 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1f260 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1f270 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1f280 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1f290 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1f2a0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1f2b0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1f2c0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1f2d0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1f2e0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1f2f0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1f300 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1f310 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1f320 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1f330 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1f340 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1f350 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1f360 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1f370 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1f380 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1f390 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1f3a0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1f3b0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1f3c0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1f3d0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1f3e0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1f3f0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1f400 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f410 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1f420 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1f430 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1f440 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1f450 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1f460 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1f470 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1f480 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1f490 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1f4a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f4b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1f4c0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1f4d0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1f4e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1f4f0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1f500 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1f510 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1f520 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1f530 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1f540 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1f550 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1f560 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1f570 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1f580 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1f590 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1f5a0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1f5b0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1f5c0 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1f5d0 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1f5e0 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1f5f0 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1f600 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1f610 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1f620 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f630 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1f640 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1f650 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1f660 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1f670 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1f680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f690 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1f6a0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f6b0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1f6c0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1f6d0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1f6e0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1f6f0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1f700 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1f710 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1f720 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1f730 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1f740 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1f750 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1f760 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1f770 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1f780 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1f790 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1f7a0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1f7b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f7c0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1f7d0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1f7e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1f7f0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1f800 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1f810 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1f820 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1f830 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1f840 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1f850 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1f860 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1f870 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1f880 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1f890 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1f8a0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1f8b0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1f8c0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1f8d0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1f8e0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1f8f0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1f900 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1f910 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1f920 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1f930 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f940 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1f950 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1f960 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f970 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1f980 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f990 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1f9a0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1f9b0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1f9c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1f9d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1f9e0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1f9f0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1fa00 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1fa10 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1fa20 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1fa30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1fa40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1fa50 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1fa60 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1fa70 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1fa80 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1fa90 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1faa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1fab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fac0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1fad0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1fae0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1faf0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1fb00 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1fb10 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1fb20 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1fb30 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1fb40 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1fb50 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1fb60 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1fb70 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1fb80 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1fb90 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1fba0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1fbb0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1fbc0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1fbd0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1fbe0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1fbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1fc00 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1fc10 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1fc20 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1fc30 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1fc40 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1fc50 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1fc60 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1fc70 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1fc80 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1fc90 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1fca0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1fcb0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1fcc0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1fcd0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1fce0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1fcf0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1fd00 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1fd10 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1fd20 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1fd30 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1fd40 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1fd50 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1fd60 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1fd70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fd80 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1fd90 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1fda0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1fdb0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1fdc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fdd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1fde0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1fdf0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1fe00 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1fe10 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1fe20 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1fe30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fe40 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1fe50 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1fe60 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1fe70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fe80 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1fe90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1fea0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1feb0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1fec0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1fed0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1fee0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1fef0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ff00 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1ff10 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1ff20 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1ff30 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1ff40 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1ff50 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1ff60 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1ff70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ff80 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1ff90 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1ffa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1ffb0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1ffc0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1ffd0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1ffe0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1fff0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
20000 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
20010 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20020 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
20030 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
20040 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20050 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
20060 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
20070 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
20080 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
20090 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
200a0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
200b0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
200c0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
200d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
200e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
200f0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
20100 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
20110 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
20120 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
20130 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
20140 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
20150 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
20160 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
20170 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20180 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
20190 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
201a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
201b0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
201c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
201d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
201e0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
201f0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
20200 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
20210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20220 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
20230 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
20240 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
20250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20260 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
20270 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
20280 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
20290 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
202a0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
202b0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
202c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
202d0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
202e0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
202f0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
20300 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
20310 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
20320 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
20330 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
20340 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
20350 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
20360 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
20370 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
20380 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
20390 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
203a0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
203b0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
203c0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
203d0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
203e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
203f0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
20400 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
20410 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
20420 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
20430 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20440 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
20450 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
20460 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
20470 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
20480 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
20490 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
204a0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
204b0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
204c0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
204d0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
204e0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
204f0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
20500 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
20510 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
20520 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
20530 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
20540 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
20550 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
20560 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
20570 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
20580 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
20590 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
205a0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
205b0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
205c0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
205d0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
205e0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
205f0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
20600 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
20610 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
20620 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
20630 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
20640 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
20650 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
20660 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
20670 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
20680 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
20690 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
206a0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
206b0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
206c0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
206d0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
206e0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
206f0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
20700 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
20710 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
20720 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
20730 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
20740 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
20750 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
20760 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
20770 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
20780 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
20790 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
207a0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
207b0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
207c0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
207d0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
207e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
207f0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
20800 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
20810 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
20820 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
20830 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
20840 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20850 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
20860 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
20870 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
20880 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
20890 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
208a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
208b0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
208c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
208d0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
208e0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
208f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
20900 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
20910 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
20920 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
20930 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
20940 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
20950 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
20960 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
20970 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
20980 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
20990 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
209a0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
209b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
209c0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
209d0 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
209e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
209f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
20a00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20a10 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
20a20 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
20a30 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
20a40 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
20a50 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
20a60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
20a70 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
20a80 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
20a90 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
20aa0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
20ab0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
20ac0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
20ad0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
20ae0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
20af0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
20b00 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
20b10 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20b20 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
20b30 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
20b40 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20b50 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
20b60 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
20b70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20b80 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
20b90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
20ba0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
20bb0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
20bc0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
20bd0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
20be0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
20bf0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
20c00 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
20c10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20c20 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
20c30 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
20c40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
20c50 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
20c60 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
20c70 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
20c80 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
20c90 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
20ca0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
20cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20cc0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20cd0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
20ce0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
20cf0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
20d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20d10 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
20d20 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
20d30 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
20d40 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
20d50 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
20d60 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
20d70 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
20d80 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
20d90 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20da0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
20db0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
20dc0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
20dd0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
20de0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20df0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
20e00 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
20e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20e20 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20e30 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
20e40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
20e50 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
20e60 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
20e70 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
20e80 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
20e90 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
20ea0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
20eb0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20ec0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
20ed0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
20ee0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20ef0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
20f00 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
20f10 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
20f20 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
20f30 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
20f40 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
20f50 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
20f60 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
20f70 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
20f80 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
20f90 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
20fa0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
20fb0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
20fc0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
20fd0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
20fe0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
20ff0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
21000 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
21010 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
21020 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
21030 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
21040 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
21050 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
21060 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
21070 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
21080 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
21090 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
210a0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
210b0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
210c0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
210d0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
210e0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
210f0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
21100 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
21110 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
21120 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
21130 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
21140 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
21150 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
21160 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
21170 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
21180 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
21190 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
211a0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
211b0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
211c0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
211d0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
211e0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
211f0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
21200 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
21210 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
21220 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
21230 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
21240 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
21250 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
21260 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
21270 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
21280 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
21290 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
212a0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
212b0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
212c0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
212d0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
212e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
212f0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
21300 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
21310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
21320 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
21330 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
21340 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
21350 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
21360 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
21370 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
21380 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
21390 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
213a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
213b0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
213c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
213d0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
213e0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
213f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
21400 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21410 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21420 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
21430 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
21440 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
21450 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21460 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
21470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21480 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
21490 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
214a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
214b0 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
214c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
214d0 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
214e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
214f0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
21500 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
21510 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
21520 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
21530 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
21540 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
21550 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
21560 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
21570 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21580 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
21590 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
215a0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
215b0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
215c0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
215d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
215e0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
215f0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
21600 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
21610 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
21620 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
21630 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
21640 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
21650 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
21660 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
21670 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
21680 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
21690 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
216a0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
216b0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
216c0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
216d0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
216e0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
216f0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21700 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
21710 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
21720 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
21730 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
21740 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21750 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
21760 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
21770 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
21780 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
21790 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
217a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
217b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
217c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
217d0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
217e0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
217f0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
21800 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
21810 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21820 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
21830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21840 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
21850 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
21860 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
21870 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
21880 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
21890 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
218a0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
218b0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
218c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
218d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
218e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
218f0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
21900 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
21910 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21920 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21930 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
21940 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
21950 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
21960 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
21970 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
21980 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
21990 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
219a0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
219b0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
219c0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
219d0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
219e0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
219f0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
21a00 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
21a10 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
21a20 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
21a30 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
21a40 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
21a50 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
21a60 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
21a70 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
21a80 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
21a90 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
21aa0 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
21ab0 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
21ac0 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
21ad0 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
21ae0 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
21af0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21b00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
21b10 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
21b20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
21b30 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
21b40 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
21b50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21b60 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21b70 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
21b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21b90 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
21ba0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
21bb0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
21bc0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
21bd0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
21be0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
21bf0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
21c00 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
21c10 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
21c20 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
21c30 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
21c40 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
21c50 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
21c60 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
21c70 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
21c80 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
21c90 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
21ca0 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
21cb0 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
21cc0 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
21cd0 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
21ce0 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
21cf0 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
21d00 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
21d10 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
21d20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
21d30 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
21d40 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
21d50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
21d60 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
21d70 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
21d80 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
21d90 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
21da0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
21db0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
21dc0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
21dd0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
21de0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
21df0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
21e00 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
21e10 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
21e20 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
21e30 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
21e40 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
21e50 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
21e60 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
21e70 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
21e80 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
21e90 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
21ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
21eb0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
21ec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
21ed0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
21ee0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
21ef0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
21f00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
21f10 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
21f20 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
21f30 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
21f40 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
21f50 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
21f60 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
21f70 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
21f80 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
21f90 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
21fa0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
21fb0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
21fc0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
21fd0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
21fe0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
21ff0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
22000 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
22010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
22020 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
22030 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
22040 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
22050 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
22060 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
22070 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
22080 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
22090 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
220a0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
220b0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
220c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
220d0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
220e0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
220f0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
22100 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
22110 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
22120 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
22130 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
22140 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
22150 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
22160 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
22170 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
22180 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
22190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
221a0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
221b0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
221c0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
221d0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
221e0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
221f0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
22200 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
22210 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
22220 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
22230 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
22240 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
22250 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
22260 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
22270 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
22280 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
22290 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
222a0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
222b0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
222c0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
222d0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
222e0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
222f0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
22300 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
22310 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
22320 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
22330 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
22340 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
22350 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
22360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
22370 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
22380 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22390 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
223a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
223b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
223c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
223d0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
223e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
223f0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
22400 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
22410 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
22420 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
22430 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22440 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
22450 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
22460 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
22470 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
22480 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
22490 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
224a0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
224b0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
224c0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
224d0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
224e0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
224f0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
22500 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22510 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
22520 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
22530 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
22540 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
22550 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22560 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22570 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
22580 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22590 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
225a0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
225b0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
225c0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
225d0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
225e0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
225f0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
22600 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
22610 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
22620 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
22630 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
22640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
22650 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
22660 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
22670 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
22680 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
22690 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
226a0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
226b0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
226c0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
226d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
226e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
226f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
22700 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
22710 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
22720 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
22730 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
22740 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
22750 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
22760 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22770 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
22780 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
22790 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
227a0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
227b0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
227c0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
227d0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
227e0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
227f0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
22800 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
22810 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22820 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
22830 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
22840 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
22850 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22860 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
22870 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
22880 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
22890 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
228a0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
228b0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
228c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
228d0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
228e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
228f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
22900 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
22910 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
22920 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
22930 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22940 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
22950 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
22960 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
22970 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
22980 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
22990 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
229a0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
229b0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
229c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
229d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
229e0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
229f0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
22a00 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
22a10 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
22a20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
22a30 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
22a40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22a50 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
22a60 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
22a70 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
22a80 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
22a90 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
22aa0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
22ab0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
22ac0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
22ad0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
22ae0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
22af0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
22b00 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
22b10 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
22b20 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
22b30 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
22b40 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
22b50 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
22b60 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
22b70 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
22b80 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
22b90 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
22ba0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
22bb0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
22bc0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
22bd0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
22be0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
22bf0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
22c00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22c10 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22c20 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
22c30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
22c40 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
22c50 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
22c60 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
22c70 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
22c80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
22c90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22ca0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
22cb0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
22cc0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
22cd0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
22ce0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
22cf0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22d00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
22d10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
22d20 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
22d30 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
22d40 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d70 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
22d80 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
22d90 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
22da0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
22db0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
22dc0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22dd0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22de0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22df0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
22e00 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
22e10 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22e20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22e30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22e40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22e50 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
22e60 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22e70 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22e80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22ea0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
22eb0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22ec0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22ed0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22ee0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22ef0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
22f00 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22f10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22f30 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
22f40 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
22f50 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22f60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f80 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
22f90 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
22fa0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22fb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22fd0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
22fe0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
22ff0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
23000 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23020 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
23030 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
23040 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
23050 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23070 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
23080 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
23090 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
230a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
230b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
230c0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
230d0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
230e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
230f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23110 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
23120 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
23130 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
23140 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23150 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23160 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
23170 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
23180 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23190 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
231a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
231b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
231c0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
231d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
231e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
231f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23200 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
23210 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
23220 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23230 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23240 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
23250 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
23260 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
23270 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
23280 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23290 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
232a0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
232b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
232c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
232d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
232e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
232f0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
23300 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23310 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23320 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23330 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
23340 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
23350 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
23360 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
23370 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
23380 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
23390 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
233a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
233b0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
233c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
233d0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
233e0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
233f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23400 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23420 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
23430 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
23440 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
23450 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23470 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
23480 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
23490 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
234a0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
234b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
234c0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
234d0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
234e0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
234f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23510 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
23520 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
23530 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
23540 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
23560 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
23570 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
23580 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
23590 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
235a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
235b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
235c0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
235d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
235e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
235f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
23600 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
23610 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
23620 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23630 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23640 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23650 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
23660 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
23670 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
23680 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
23690 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
236a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
236b0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
236c0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
236d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
236e0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
236f0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
23700 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
23710 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
23720 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
23730 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
23740 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
23750 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
23760 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
23770 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
23780 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
23790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
237a0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
237b0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
237c0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
237d0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
237e0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
237f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23800 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
23810 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
23820 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
23830 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
23840 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
23860 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
23870 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
23880 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
23890 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
238a0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
238b0 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
238c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
238d0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
238e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
238f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
23900 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
23910 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
23920 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
23930 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
23940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
23950 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
23960 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
23970 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
23980 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
23990 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
239a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
239b0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
239c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
239d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
239e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
239f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23a00 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
23a10 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
23a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
23a30 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
23a40 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
23a50 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
23a60 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
23a70 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
23a80 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
23a90 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
23aa0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
23ab0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
23ac0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
23ad0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
23ae0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
23af0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
23b00 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
23b10 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
23b20 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
23b30 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
23b40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
23b50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
23b60 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
23b70 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
23b80 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
23b90 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
23ba0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
23bb0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
23bc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23bd0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
23be0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23bf0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
23c00 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
23c10 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
23c20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
23c30 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
23c40 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
23c50 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
23c60 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
23c70 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
23c80 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
23c90 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
23ca0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
23cb0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
23cc0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
23cd0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
23ce0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
23cf0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
23d00 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
23d10 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
23d20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
23d30 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
23d40 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
23d50 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
23d60 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
23d70 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
23d80 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23d90 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
23da0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
23db0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
23dc0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
23dd0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
23de0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
23df0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
23e00 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
23e10 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
23e20 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
23e30 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
23e40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
23e50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
23e60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
23e70 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  race(sqlite3*,. 
23e80 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28    void(*xTrace)(
23e90 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
23ea0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
23eb0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
23ec0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
23ed0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
23ee0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
23ef0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
23f00 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
23f10 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
23f20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
23f30 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
23f40 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
23f50 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
23f60 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23f70 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
23f80 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
23f90 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
23fa0 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
23fb0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23fc0 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
23fd0 67 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67 75  gic.  The M argu
23fe0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
23ff0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
24000 2c 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d  ,X,P)] is an OR-
24010 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
24020 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
24030 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24040 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
24050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24060 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
24070 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
24080 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
24090 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
240a0 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
240b0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
240c0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
240d0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
240e0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
240f0 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
24100 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
24110 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
24120 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
24130 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
24140 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
24150 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
24160 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
24170 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
24180 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
24190 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
241a0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
241b0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
241c0 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
241d0 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
241e0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
241f0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
24200 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
24210 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
24220 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
24230 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
24240 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
24250 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24260 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
24270 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
24280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24290 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
242a0 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
242b0 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
242c0 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
242d0 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
242e0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
242f0 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
24300 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
24310 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
24320 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
24330 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
24340 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
24350 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
24360 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
24370 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
24380 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
24390 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
243a0 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
243b0 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
243c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
243d0 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
243e0 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
243f0 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
24400 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
24410 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
24420 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
24430 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
24440 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
24450 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
24460 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
24470 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
24480 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
24490 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
244a0 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
244b0 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
244c0 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
244d0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
244e0 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
244f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
24500 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
24510 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
24520 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
24530 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
24540 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
24550 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
24560 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
24570 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
24580 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
24590 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
245a0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
245b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
245c0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
245d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
245e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
245f0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
24600 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
24610 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
24620 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
24630 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
24640 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
24650 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
24660 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
24670 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
24680 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
24690 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
246a0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
246b0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
246c0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
246d0 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
246e0 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
246f0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
24700 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
24710 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24720 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
24730 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
24740 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
24750 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
24760 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
24770 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
24780 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
24790 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
247a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
247b0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
247c0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
247d0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
247e0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
247f0 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
24800 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
24810 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
24820 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
24830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24840 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
24850 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
24860 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
24870 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
24880 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
24890 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
248a0 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
248b0 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
248c0 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
248d0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
248e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
248f0 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
24900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24910 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
24920 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
24930 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
24940 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
24950 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
24960 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
24970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24980 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
24990 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
249a0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
249b0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
249c0 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
249d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
249e0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
249f0 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
24a00 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
24a10 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
24a20 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
24a30 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
24a40 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
24a50 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
24a60 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
24a70 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
24a80 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
24a90 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
24aa0 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
24ab0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
24ac0 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
24ad0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
24ae0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
24af0 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
24b00 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
24b10 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
24b20 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
24b30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
24b40 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
24b50 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
24b60 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
24b70 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
24b80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
24b90 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
24ba0 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
24bb0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
24bc0 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
24bd0 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
24be0 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
24bf0 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
24c00 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
24c10 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
24c20 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
24c30 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
24c40 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
24c50 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
24c60 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
24c70 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
24c80 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
24c90 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
24ca0 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
24cb0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
24cc0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
24cd0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
24ce0 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
24cf0 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
24d00 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
24d10 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
24d20 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
24d30 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
24d40 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
24d50 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
24d60 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
24d70 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
24d80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
24d90 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
24da0 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
24db0 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
24dc0 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
24dd0 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
24de0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24df0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
24e00 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
24e10 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
24e20 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
24e30 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
24e40 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
24e50 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
24e60 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
24e70 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
24e80 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
24e90 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
24ea0 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
24eb0 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
24ec0 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
24ed0 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
24ee0 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
24ef0 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
24f00 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
24f10 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
24f20 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
24f30 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
24f40 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
24f50 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
24f60 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
24f70 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
24f80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
24f90 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
24fa0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
24fb0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
24fc0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
24fd0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
24fe0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
24ff0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
25000 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
25010 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25020 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
25030 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
25040 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
25050 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
25060 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
25070 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
25080 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
25090 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
250a0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
250b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
250c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
250d0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
250e0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
250f0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
25100 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
25110 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
25120 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
25130 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
25140 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
25150 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
25160 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
25170 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
25180 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
25190 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
251a0 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
251b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
251c0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
251d0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
251e0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
251f0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
25200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25210 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
25220 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
25230 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
25240 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
25250 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
25260 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
25270 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
25280 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
25290 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
252a0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
252b0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
252c0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
252d0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
252e0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
252f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
25300 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
25310 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
25320 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
25330 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
25340 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
25350 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
25360 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
25370 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
25380 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
25390 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
253a0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
253b0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
253c0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
253d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
253e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
253f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
25400 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
25410 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
25420 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25430 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25440 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
25450 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
25460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25470 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
25480 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
25490 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
254a0 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
254b0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
254c0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
254d0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
254e0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
254f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
25500 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
25510 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
25520 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
25530 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
25540 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
25550 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
25560 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
25570 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
25580 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
25590 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
255a0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
255b0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
255c0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
255d0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
255e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
255f0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
25600 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
25610 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
25620 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
25630 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
25640 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
25650 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
25660 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
25670 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
25680 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
25690 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
256a0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
256b0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
256c0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
256d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
256e0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
256f0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
25700 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
25710 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
25720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
25730 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
25740 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
25750 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25760 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
25770 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
25780 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
25790 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
257a0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
257b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
257c0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
257d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
257e0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
257f0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
25800 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
25810 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
25820 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
25830 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
25840 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
25850 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
25860 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
25870 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
25880 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
25890 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
258a0 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
258b0 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
258c0 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
258d0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
258e0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
258f0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
25900 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
25910 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
25920 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
25930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
25940 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
25950 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
25960 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
25970 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
25980 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
25990 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
259a0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
259b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
259c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
259d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
259e0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
259f0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
25a00 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
25a10 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
25a20 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
25a30 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
25a40 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
25a50 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
25a60 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
25a70 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
25a80 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
25a90 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
25aa0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
25ab0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
25ac0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
25ad0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
25ae0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
25af0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
25b00 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
25b10 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
25b20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
25b30 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
25b40 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
25b50 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
25b60 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
25b70 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
25b80 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
25b90 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
25ba0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
25bb0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
25bc0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
25bd0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
25be0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
25bf0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
25c00 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
25c10 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
25c20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
25c30 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25c40 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
25c50 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
25c60 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
25c70 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
25c80 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
25c90 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
25ca0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
25cb0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
25cc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25cd0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25ce0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
25cf0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
25d00 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
25d10 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
25d20 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
25d30 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
25d40 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25d50 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
25d60 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
25d70 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
25d80 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
25d90 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
25da0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
25db0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
25dc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25dd0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
25de0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
25df0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
25e00 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
25e10 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
25e20 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
25e30 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
25e40 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
25e50 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
25e60 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
25e70 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
25e80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
25e90 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
25ea0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
25eb0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
25ec0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
25ed0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25ee0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
25ef0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
25f00 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
25f10 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
25f20 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
25f30 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
25f40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25f50 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
25f60 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
25f70 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
25f80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
25f90 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
25fa0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
25fb0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
25fc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25fd0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
25fe0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
25ff0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
26000 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
26010 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
26020 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
26030 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
26040 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
26050 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
26060 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
26070 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
26080 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
26090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
260a0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
260b0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
260c0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
260d0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
260e0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
260f0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
26100 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
26110 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
26120 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
26130 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
26140 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
26150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26160 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
26170 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
26180 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
26190 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
261a0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
261b0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
261c0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
261d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
261e0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
261f0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
26200 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
26210 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
26220 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
26230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
26240 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
26250 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
26260 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
26270 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
26280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
26290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
262a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
262b0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
262c0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
262d0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
262e0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
262f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
26300 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
26310 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
26320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
26330 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
26340 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
26350 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
26360 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
26370 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
26380 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
26390 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
263a0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
263b0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
263c0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
263d0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
263e0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
263f0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
26400 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
26410 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
26420 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
26430 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
26440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26450 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
26460 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
26470 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
26480 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
26490 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
264a0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
264b0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
264c0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
264d0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
264e0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
264f0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26500 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
26510 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
26520 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
26530 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
26540 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
26550 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
26560 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
26570 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
26580 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
26590 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
265a0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
265b0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
265c0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
265d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
265e0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
265f0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
26600 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
26610 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
26620 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
26630 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26640 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
26650 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
26660 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
26670 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
26680 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
26690 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
266a0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
266b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
266c0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
266d0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
266e0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
266f0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
26700 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
26710 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
26720 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
26730 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
26740 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
26750 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
26760 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
26770 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69  * set in the thi
26780 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
26790 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
267a0 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
267b0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
267c0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
267d0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
267e0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
267f0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
26800 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
26810 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
26820 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
26830 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
26840 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  n..** URI filena
26850 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
26860 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
26870 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
26880 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
26890 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
268a0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
268b0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
268c0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
268d0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
268e0 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
268f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
26900 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
26910 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
26920 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
26930 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
26940 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
26950 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
26960 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
26970 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
26980 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
26990 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
269a0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
269b0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
269c0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
269d0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
269e0 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
269f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
26a00 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
26a10 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
26a20 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
26a30 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
26a40 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
26a50 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
26a60 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
26a70 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
26a80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26a90 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
26aa0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
26ab0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
26ac0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
26ad0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
26ae0 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
26af0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
26b00 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
26b10 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
26b20 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
26b30 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
26b40 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
26b50 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
26b60 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
26b70 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
26b80 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
26b90 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
26ba0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
26bb0 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
26bc0 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
26bd0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
26be0 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
26bf0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
26c00 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
26c10 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
26c20 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
26c30 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
26c40 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
26c50 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
26c60 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
26c70 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
26c80 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
26c90 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
26ca0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
26cb0 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
26cc0 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
26cd0 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
26ce0 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
26cf0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
26d00 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
26d10 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
26d20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
26d30 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
26d40 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
26d50 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
26d60 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
26d70 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
26d80 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
26d90 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
26da0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
26db0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
26dc0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
26dd0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
26de0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
26df0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
26e00 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
26e10 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
26e20 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
26e30 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
26e40 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
26e50 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
26e60 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
26e70 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
26e80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26e90 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
26ea0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
26eb0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
26ec0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
26ed0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
26ee0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
26ef0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
26f00 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
26f10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
26f20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26f30 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
26f40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
26f50 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
26f60 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
26f70 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
26f80 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
26f90 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
26fa0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
26fb0 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
26fc0 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
26fd0 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
26fe0 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
26ff0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
27000 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
27010 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
27020 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
27030 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
27040 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
27050 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
27060 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
27070 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
27080 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
27090 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
270a0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
270b0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
270c0 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
270d0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
270e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
270f0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
27100 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
27110 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
27120 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
27130 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
27140 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
27150 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
27160 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
27170 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
27180 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
27190 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
271a0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
271b0 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
271c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
271d0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
271e0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
271f0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
27200 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
27210 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
27220 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
27230 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
27240 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
27250 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
27260 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
27270 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
27280 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
27290 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
272a0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
272b0 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
272c0 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
272d0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
272e0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
272f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27300 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
27310 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
27320 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
27330 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
27340 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
27350 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
27360 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
27370 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
27380 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
27390 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
273a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
273b0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
273c0 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
273d0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
273e0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
273f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27400 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
27410 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
27420 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
27430 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
27440 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
27450 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
27460 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
27470 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
27480 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
27490 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
274a0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
274b0 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
274c0 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
274d0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
274e0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
274f0 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
27500 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
27510 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27520 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
27530 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
27540 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
27550 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
27560 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
27570 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
27580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27590 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
275a0 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
275b0 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
275c0 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
275d0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
275e0 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
275f0 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
27600 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
27610 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
27620 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
27630 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
27640 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
27650 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
27660 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
27670 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
27680 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
27690 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
276a0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
276b0 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
276c0 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
276d0 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
276e0 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
276f0 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
27700 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
27710 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
27720 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
27730 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
27740 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
27750 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
27760 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
27770 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
27780 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
27790 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
277a0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
277b0 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
277c0 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
277d0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
277e0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
277f0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
27800 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
27810 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
27820 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
27830 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
27840 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
27850 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
27860 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
27870 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
27880 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
27890 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
278a0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
278b0 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
278c0 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
278d0 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
278e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
278f0 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
27900 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
27910 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
27920 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
27930 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
27940 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
27950 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
27960 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
27970 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
27980 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
27990 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
279a0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
279b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
279c0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
279d0 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
279e0 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
279f0 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
27a00 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
27a10 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
27a20 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
27a30 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
27a40 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
27a50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
27a60 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
27a70 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
27a80 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
27a90 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
27aa0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
27ab0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
27ac0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
27ad0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
27ae0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
27af0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
27b00 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
27b10 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
27b20 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
27b30 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
27b40 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
27b50 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
27b60 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
27b70 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
27b80 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
27b90 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
27ba0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
27bb0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
27bc0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
27bd0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27be0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
27bf0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
27c00 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
27c10 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
27c20 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
27c30 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
27c40 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
27c50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27c60 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
27c70 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
27c80 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
27c90 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
27ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27cb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
27cc0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
27cd0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
27ce0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
27cf0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
27d00 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
27d10 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
27d20 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
27d30 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
27d40 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
27d50 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
27d60 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
27d70 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
27d80 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
27d90 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
27da0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
27db0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
27dc0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
27dd0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
27de0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
27df0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
27e00 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
27e10 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
27e20 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
27e30 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
27e40 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
27e50 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
27e60 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
27e70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
27e80 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
27e90 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
27ea0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
27eb0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
27ec0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
27ed0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
27ee0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
27ef0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
27f00 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
27f10 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
27f20 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
27f30 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
27f40 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
27f50 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27f60 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
27f70 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
27f80 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
27f90 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
27fa0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
27fb0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
27fc0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
27fd0 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
27fe0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
27ff0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
28000 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
28010 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
28020 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
28030 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
28040 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
28050 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
28060 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
28070 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
28080 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
28090 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
280a0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
280b0 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
280c0 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
280d0 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
280e0 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
280f0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
28100 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
28110 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
28120 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
28130 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
28140 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
28150 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
28160 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
28170 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
28180 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
28190 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
281a0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
281b0 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
281c0 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
281d0 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
281e0 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
281f0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
28200 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
28210 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
28220 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
28230 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
28240 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
28250 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
28260 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
28270 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
28280 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
28290 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
282a0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
282b0 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
282c0 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
282d0 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
282e0 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
282f0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
28300 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
28310 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
28320 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
28330 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
28340 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
28350 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
28360 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
28370 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
28380 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
28390 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
283a0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
283b0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
283c0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
283d0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
283e0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
283f0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
28400 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
28410 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
28420 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
28430 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
28440 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
28450 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
28460 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
28470 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
28480 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
28490 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
284a0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
284b0 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
284c0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
284d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
284e0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
284f0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
28500 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
28510 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
28520 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
28530 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
28540 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
28550 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
28560 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
28570 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28580 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
28590 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
285a0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
285b0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
285c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
285d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
285e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
285f0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
28600 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
28610 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
28620 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
28630 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
28640 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
28650 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
28660 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
28670 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
28680 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
28690 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
286a0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
286b0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
286c0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
286d0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
286e0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
286f0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
28700 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
28710 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
28720 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
28730 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
28740 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
28750 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
28760 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
28770 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
28780 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
28790 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
287a0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
287b0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
287c0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
287d0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
287e0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
287f0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
28800 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
28810 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
28820 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
28830 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
28840 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
28850 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
28860 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28870 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
28880 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28890 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
288a0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
288b0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
288c0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
288d0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
288e0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
288f0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
28900 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
28910 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
28920 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
28930 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
28940 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
28950 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
28960 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
28970 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
28980 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
28990 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
289a0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
289b0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
289c0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
289d0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
289e0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
289f0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
28a00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28a10 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
28a20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
28a30 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
28a40 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
28a50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28a60 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28a70 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
28a80 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
28a90 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
28aa0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
28ab0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28ac0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
28ad0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
28ae0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
28af0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
28b00 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
28b10 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
28b20 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
28b30 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
28b40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28b50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
28b60 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
28b70 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
28b80 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
28b90 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
28ba0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
28bb0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
28bc0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
28bd0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
28be0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
28bf0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
28c00 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28c10 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
28c20 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
28c30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
28c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28c50 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
28c60 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
28c70 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
28c80 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
28c90 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
28ca0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
28cb0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
28cc0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
28cd0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
28ce0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
28cf0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
28d00 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
28d10 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
28d20 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28d30 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
28d40 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
28d50 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
28d60 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
28d70 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
28d80 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
28d90 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
28da0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
28db0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
28dc0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
28dd0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
28de0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
28df0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
28e00 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
28e10 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
28e20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
28e30 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
28e40 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
28e50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
28e60 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
28e70 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
28e80 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28e90 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
28ea0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
28eb0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
28ec0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
28ed0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
28ee0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
28ef0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
28f00 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
28f10 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
28f20 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
28f30 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
28f40 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
28f50 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
28f60 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
28f70 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28f80 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28f90 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
28fa0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
28fb0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
28fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
28fd0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
28fe0 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
28ff0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
29000 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
29010 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
29020 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
29030 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
29040 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
29050 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
29060 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
29070 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
29080 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
29090 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
290a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
290b0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
290c0 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
290d0 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
290e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
290f0 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
29100 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
29110 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
29120 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
29130 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
29140 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
29150 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
29160 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
29170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
29180 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
29190 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
291a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
291b0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
291c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
291d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
291e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
291f0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
29200 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
29210 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
29220 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
29230 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
29240 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
29250 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
29260 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
29270 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
29280 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
29290 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
292a0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
292b0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
292c0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
292d0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
292e0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
292f0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
29300 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
29310 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
29320 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
29330 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
29340 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
29350 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
29360 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
29370 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
29380 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
29390 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
293a0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
293b0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
293c0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
293d0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
293e0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
293f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
29400 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
29410 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
29420 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
29430 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
29440 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29450 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
29460 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
29470 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
29480 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
29490 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
294a0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
294b0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
294c0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
294d0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
294e0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
294f0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
29500 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
29510 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
29520 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
29530 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
29540 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
29550 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
29560 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
29570 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
29580 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
29590 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
295a0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
295b0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
295c0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
295d0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
295e0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
295f0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
29600 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
29610 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
29620 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
29630 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
29640 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
29650 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
29660 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
29670 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
29680 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
29690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
296a0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
296b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
296c0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
296d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
296e0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
296f0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
29700 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
29710 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
29720 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
29730 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
29740 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
29750 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
29760 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
29770 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
29780 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
29790 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
297a0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
297b0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
297c0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
297d0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
297e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
297f0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
29800 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
29810 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
29820 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
29830 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
29840 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
29850 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
29860 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
29870 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
29880 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
29890 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
298a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
298b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
298c0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
298d0 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
298e0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
298f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
29900 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
29910 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
29920 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
29930 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29940 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
29950 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
29960 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
29970 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
29980 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
29990 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
299a0 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
299b0 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
299c0 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
299d0 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
299e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
299f0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
29a00 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
29a10 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
29a20 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
29a30 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
29a40 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
29a50 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
29a60 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
29a70 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
29a80 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
29a90 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
29aa0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
29ab0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
29ac0 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
29ad0 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
29ae0 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
29af0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
29b00 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
29b10 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
29b20 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
29b30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
29b40 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
29b50 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
29b60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
29b70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
29b80 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
29b90 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
29ba0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
29bb0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
29bc0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
29bd0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
29be0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
29bf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29c00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
29c10 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
29c20 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
29c30 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
29c40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29c50 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
29c60 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
29c70 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
29c80 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
29c90 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
29ca0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
29cb0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29cc0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
29cd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
29ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
29cf0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
29d00 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
29d10 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
29d20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
29d30 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
29d40 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
29d50 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
29d60 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
29d70 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
29d80 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
29d90 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
29da0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
29db0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
29dc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29dd0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
29de0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
29df0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
29e00 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
29e10 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
29e20 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
29e30 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
29e40 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
29e50 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
29e60 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
29e70 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
29e80 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
29e90 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
29ea0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
29eb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
29ec0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
29ed0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
29ee0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
29ef0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
29f00 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
29f10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
29f20 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
29f30 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
29f40 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
29f50 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
29f60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
29f70 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
29f80 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
29f90 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
29fa0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
29fb0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
29fc0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
29fd0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
29fe0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
29ff0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
2a000 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
2a010 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
2a020 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
2a030 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
2a040 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
2a050 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
2a060 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
2a070 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2a080 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
2a090 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
2a0a0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
2a0b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a0c0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
2a0d0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
2a0e0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
2a0f0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
2a100 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
2a110 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
2a120 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
2a130 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
2a140 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
2a150 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
2a160 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
2a170 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
2a180 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
2a190 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
2a1a0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
2a1b0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
2a1c0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2a1d0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
2a1e0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
2a1f0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
2a200 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
2a210 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
2a220 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
2a230 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
2a240 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
2a250 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
2a260 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
2a270 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
2a280 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
2a290 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
2a2a0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
2a2b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
2a2c0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
2a2d0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
2a2e0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
2a2f0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
2a300 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
2a310 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
2a320 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
2a330 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
2a340 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
2a350 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
2a360 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
2a370 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
2a380 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
2a390 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
2a3a0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
2a3b0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
2a3c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
2a3d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
2a3e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
2a3f0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
2a400 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
2a410 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
2a420 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
2a430 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
2a440 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
2a450 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
2a460 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
2a470 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
2a480 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
2a490 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
2a4a0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
2a4b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
2a4c0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
2a4d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
2a4e0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
2a4f0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
2a500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
2a510 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
2a520 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
2a530 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
2a540 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
2a550 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
2a560 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2a570 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
2a580 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
2a590 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2a5a0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
2a5b0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
2a5c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
2a5d0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
2a5e0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
2a5f0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
2a600 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
2a610 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
2a620 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
2a630 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
2a640 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
2a650 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
2a660 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
2a670 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
2a680 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a690 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
2a6a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a6b0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
2a6c0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
2a6d0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
2a6e0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
2a6f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a700 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
2a710 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a720 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
2a730 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a740 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
2a750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a760 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
2a770 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a780 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
2a790 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a7a0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
2a7b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a7c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a7d0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
2a7e0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
2a7f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
2a800 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
2a810 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
2a820 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a830 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
2a840 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
2a850 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
2a860 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
2a870 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a880 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
2a890 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a8a0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
2a8b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a8c0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
2a8d0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
2a8e0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
2a8f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a900 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
2a910 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
2a920 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a930 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
2a940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a950 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a960 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
2a970 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
2a980 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
2a990 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a9a0 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
2a9b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a9c0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
2a9d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a9e0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
2a9f0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
2aa00 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
2aa10 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
2aa20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
2aa30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2aa40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aa50 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65  _v2()] or.** the
2aa60 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65   equivalent trie
2aa70 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70  s to allocate sp
2aa80 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61  ace for more tha
2aa90 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f  n this many opco
2aaa0 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67  des.** in a sing
2aab0 6c 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  le prepared stat
2aac0 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45  ement, an SQLITE
2aad0 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20  _NOMEM error is 
2aae0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
2aaf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2ab00 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2ab10 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
2ab20 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2ab30 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
2ab40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2ab50 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2ab60 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
2ab70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2ab80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2ab90 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
2aba0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2abb0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
2abc0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2abd0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
2abe0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2abf0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
2ac00 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ac10 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2ac20 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
2ac30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2ac40 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
2ac50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2ac60 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
2ac70 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
2ac80 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
2ac90 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
2aca0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
2acb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2acc0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2acd0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
2ace0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2acf0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ad00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ad10 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
2ad20 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
2ad30 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
2ad40 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
2ad50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2ad60 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2ad70 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2ad80 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2ad90 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
2ada0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
2adb0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
2adc0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
2add0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2ade0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2adf0 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64  R_THREADS]] ^(<d
2ae00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  t>SQLITE_LIMIT_W
2ae10 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64  ORKER_THREADS</d
2ae20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2ae30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2ae40 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72  auxiliary worker
2ae50 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20   threads that a 
2ae60 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61  single.** [prepa
2ae70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d  red statement] m
2ae80 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e  ay start.</dd>)^
2ae90 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2aea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2aeb0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
2aec0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
2aed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2aee0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
2aef0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
2af00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2af10 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
2af20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
2af30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2af40 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
2af50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
2af60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2af70 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2af80 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
2af90 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2afa0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
2afb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2afc0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
2afd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2afe0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
2aff0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
2b000 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2b010 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
2b020 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
2b030 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2b040 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
2b050 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
2b060 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2b070 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
2b080 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
2b090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2b0a0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
2b0b0 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
2b0c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2b0d0 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20  KER_THREADS     
2b0e0 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20        11../*.** 
2b0f0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
2b100 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  e Flags.**.** Th
2b110 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
2b120 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61  fine various fla
2b130 67 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  gs that can be p
2b140 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70  assed into.** "p
2b150 72 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65  repFlags" parame
2b160 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ter of the [sqli
2b170 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2b180 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
2b190 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b1a0 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  ] interfaces..**
2b1b0 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61  .** New flags ma
2b1c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2b1d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2b1e0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c   SQLite..**.** <
2b1f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
2b200 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2b210 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  NT]] ^(<dt>SQLIT
2b220 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2b230 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  TENT</dt>.** <dd
2b240 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50  >The SQLITE_PREP
2b250 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66  ARE_PERSISTENT f
2b260 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f  lag is a hint to
2b270 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e   the query plann
2b280 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2b290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b2a0 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e  t will be retain
2b2b0 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69  ed for a long ti
2b2c0 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62  me and.** probab
2b2d0 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74  ly reused many t
2b2e0 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74  imes.)^ ^Without
2b2f0 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c   this flag, [sql
2b300 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b310 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2b320 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2b330 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74  )] assume that t
2b340 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b350 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62  ement will .** b
2b360 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65  e used just once
2b370 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65   or at most a fe
2b380 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e  w times and then
2b390 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67   destroyed using
2b3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2b3b0 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76  alize()] relativ
2b3c0 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75  ely soon. The cu
2b3d0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
2b3e0 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20  tion acts.** on 
2b3f0 74 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f  this hint by avo
2b400 69 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66  iding the use of
2b410 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
2b420 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f  ry] so as not to
2b430 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20  .** deplete the 
2b440 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66  limited store of
2b450 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
2b460 79 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  y. Future versio
2b470 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20  ns of.** SQLite 
2b480 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20  may act on this 
2b490 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79  hint differently
2b4a0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
2b4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45  efine SQLITE_PRE
2b4c0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20  PARE_PERSISTENT 
2b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
2b4e0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
2b4f0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
2b500 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2b510 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2b520 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
2b530 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
2b540 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
2b550 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
2b560 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
2b570 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74  cute an SQL stat
2b580 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66  ement, it must f
2b590 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
2b5a0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
2b5b0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
2b5c0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
2b5d0 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69  routines.  Or, i
2b5e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2b5f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2b600 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72   are constructor
2b610 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  s for the [prepa
2b620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2b630 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  bject..**.** The
2b640 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69   preferred routi
2b650 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71  ne to use is [sq
2b660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b670 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ()].  The.** [sq
2b680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2b690 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65   interface is le
2b6a0 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20  gacy and should 
2b6b0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b  be avoided..** [
2b6c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b6d0 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74  v3()] has an ext
2b6e0 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f  ra "prepFlags" o
2b6f0 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73  ption that is us
2b700 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61  ed.** for specia
2b710 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  l purposes..**.*
2b720 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65  * The use of the
2b730 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2b740 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20  s is preferred, 
2b750 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e  as SQLite curren
2b760 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20  tly.** does all 
2b770 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54  parsing using UT
2b780 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36  F-8.  The UTF-16
2b790 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2b7a0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61  provided.** as a
2b7b0 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54   convenience.  T
2b7c0 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2b7d0 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e  aces work by con
2b7e0 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69  verting the.** i
2b7f0 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55  nput text into U
2b800 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  TF-8, then invok
2b810 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ing the correspo
2b820 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65  nding UTF-8 inte
2b830 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
2b840 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
2b850 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
2b860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b870 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
2b880 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
2b890 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2b8a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2b8b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2b8c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2b8d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
2b8e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2b8f0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
2b900 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
2b910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
2b920 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
2b930 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
2b940 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2b950 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
2b960 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
2b970 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
2b980 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b990 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2b9a0 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64  are_v2(),.** and
2b9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b9c0 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v3().** interfa
2b9d0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2b9e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2b9f0 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f  re16(), sqlite3_
2ba00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a  prepare16_v2(),.
2ba10 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  ** and sqlite3_p
2ba20 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73  repare16_v3() us
2ba30 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
2ba40 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
2ba50 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
2ba60 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
2ba70 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
2ba80 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
2ba90 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
2baa0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
2bab0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
2bac0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2bad0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
2bae0 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
2baf0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
2bb00 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2bb10 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
2bb20 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
2bb30 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
2bb40 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
2bb50 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
2bb60 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
2bb70 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
2bb80 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
2bb90 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
2bba0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
2bbb0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
2bbc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2bbd0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
2bbe0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
2bbf0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
2bc00 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
2bc10 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
2bc20 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2bc30 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
2bc40 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
2bc50 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
2bc60 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
2bc70 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
2bc80 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
2bc90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
2bca0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
2bcb0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
2bcc0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
2bcd0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
2bce0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
2bcf0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
2bd00 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
2bd10 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
2bd20 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
2bd30 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
2bd40 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
2bd50 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
2bd60 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2bd70 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
2bd80 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2bd90 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
2bda0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
2bdb0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
2bdc0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
2bdd0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
2bde0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
2bdf0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2be00 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2be10 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2be20 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2be30 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2be40 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2be50 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2be60 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2be70 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2be80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2be90 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2bea0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2beb0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2bec0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2bed0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2bee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2bef0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2bf00 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2bf10 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2bf20 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2bf30 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2bf40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2bf50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2bf60 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2bf70 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f  e_v3(), sqlite3_
2bf80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a  prepare16_v2(),.
2bf90 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  ** and sqlite3_p
2bfa0 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e  repare16_v3() in
2bfb0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63  terfaces are rec
2bfc0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
2bfd0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a   new programs..*
2bfe0 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65  * The older inte
2bff0 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f  rfaces (sqlite3_
2c000 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
2c010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c020 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e  )).** are retain
2c030 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2c040 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2c050 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2c060 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2c070 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e   ^In the "vX" in
2c080 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2c090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c0a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2c0b0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2c0c0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2c0d0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2c0e0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2c0f0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2c100 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2c110 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2c120 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2c130 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2c140 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2c150 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2c160 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2c170 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2c180 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2c190 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2c1a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2c1b0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2c1c0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2c1d0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2c1e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2c1f0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2c200 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2c210 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2c220 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2c230 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2c240 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2c250 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2c260 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2c270 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2c280 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2c290 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2c2a0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2c2b0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2c2c0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2c2d0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2c2e0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2c2f0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2c300 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2c310 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2c320 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2c330 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2c340 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2c350 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2c360 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2c370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2c380 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2c390 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2c3a0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2c3b0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2c3c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2c3d0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2c3e0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2c3f0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2c400 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2c410 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2c420 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2c430 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2c440 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2c450 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2c460 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2c470 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2c480 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2c490 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2c4a0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2c4b0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2c4c0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2c4d0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2c4e0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2c4f0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2c500 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2c510 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2c520 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2c530 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2c540 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2c550 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2c560 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2c570 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2c580 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2c590 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2c5a0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2c5b0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2c5c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2c5d0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2c5e0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2c5f0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2c600 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2c610 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2c620 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2c630 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2c640 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2c650 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2c660 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2c670 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2c680 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2c690 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2c6a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2c6b0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2c6c0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2c6d0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2c6e0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2c6f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2c700 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2c710 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2c720 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70  <p>^sqlite3_prep
2c730 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73  are_v3() differs
2c740 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72   from sqlite3_pr
2c750 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20  epare_v2() only 
2c760 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65  in having.** the
2c770 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73   extra prepFlags
2c780 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
2c790 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79  h is a bit array
2c7a0 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a   consisting of z
2c7b0 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f  ero or.** more o
2c7c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52  f the [SQLITE_PR
2c7d0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2c7e0 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  |SQLITE_PREPARE_
2c7f0 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a  *] flags.  ^The.
2c800 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2c810 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  re_v2() interfac
2c820 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  e works exactly 
2c830 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
2c840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c850 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20  3() with a zero 
2c860 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2c870 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ter..** </ol>.*/
2c880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c890 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
2c8a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c8b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c8c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c8d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c8e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c8f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2c900 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c910 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c920 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c930 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c940 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c950 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c960 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c970 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c980 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2c990 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c9a0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c9b0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c9c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c9d0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
2c9e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c9f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ca00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ca10 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ca20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ca30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2ca40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ca50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ca60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ca70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2ca80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2ca90 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2caa0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2cab0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2cac0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2cad0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2cae0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2caf0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2cb00 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2cb10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2cb20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2cb30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2cb40 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2cb50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2cb60 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2cb70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2cb80 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2cb90 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2cba0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2cbb0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2cbc0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2cbd0 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70    unsigned int p
2cbe0 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72  repFlags, /* Zer
2cbf0 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45  o or more SQLITE
2cc00 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20  _PREPARE_ flags 
2cc10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2cc20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2cc30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2cc40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cc50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2cc60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2cc70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2cc80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2cc90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2cca0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
2ccb0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ccc0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ccd0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2cce0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2ccf0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2cd00 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2cd10 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2cd20 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2cd30 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2cd40 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2cd50 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2cd60 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2cd70 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2cd80 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2cd90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2cda0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2cdb0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2cdc0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2cdd0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2cde0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2cdf0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2ce00 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ce10 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ce20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2ce30 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2ce40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ce50 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2ce60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ce70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ce80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ce90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2cea0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ceb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cec0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ced0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cee0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2cef0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cf00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cf10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cf20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cf30 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71  epare16_v3(.  sq
2cf40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2cf50 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2cf60 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2cf70 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2cf80 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2cf90 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2cfa0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2cfb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2cfc0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2cfd0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2cfe0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2cff0 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2d000 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2d010 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2d020 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2d030 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2d040 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2d050 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2d060 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d070 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2d080 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2d090 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2d0a0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2d0b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2d0c0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2d0d0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2d0e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2d0f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d100 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2d110 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2d120 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2d130 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2d140 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2d150 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2d160 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2d170 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2d180 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
2d190 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2d1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d1b0 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  3()],.** [sqlite
2d1c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d1d0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ], or [sqlite3_p
2d1e0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
2d1f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d200 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20  expanded_sql(P) 
2d210 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d220 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2d230 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
2d240 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2d250 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70  SQL text of prep
2d260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2d270 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20   with.** [bound 
2d280 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61  parameters] expa
2d290 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  nded..**.** ^(Fo
2d2a0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20  r example, if a 
2d2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d2c0 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73  nt is created us
2d2d0 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74  ing the SQL.** t
2d2e0 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63  ext "SELECT $abc
2d2f0 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61  ,:xyz" and if pa
2d300 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20  rameter $abc is 
2d310 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72  bound to integer
2d320 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72   2345.** and par
2d330 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75  ameter :xyz is u
2d340 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c  nbound, then sql
2d350 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20  ite3_sql() will 
2d360 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72  return.** the or
2d370 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22  iginal string, "
2d380 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a  SELECT $abc,:xyz
2d390 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78  " but sqlite3_ex
2d3a0 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20  panded_sql().** 
2d3b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c  will return "SEL
2d3c0 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29  ECT 2345,NULL".)
2d3d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2d3e0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d3f0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  l() interface re
2d400 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e  turns NULL if in
2d410 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
2d420 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c  y.** is availabl
2d430 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  e to hold the re
2d440 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20  sult, or if the 
2d450 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63  result would exc
2d460 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d  eed the.** the m
2d470 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65  aximum string le
2d480 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20  ngth determined 
2d490 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c  by the [SQLITE_L
2d4a0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  IMIT_LENGTH]..**
2d4b0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
2d4c0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
2d4d0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2d4e0 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68  option limits th
2d4f0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75  e size of.** bou
2d500 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70  nd parameter exp
2d510 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b  ansions.  ^The [
2d520 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43  SQLITE_OMIT_TRAC
2d530 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  E] compile-time.
2d540 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73  ** option causes
2d550 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d560 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79  d_sql() to alway
2d570 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a  s return NULL..*
2d580 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  *.** ^The string
2d590 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d5a0 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d  ite3_sql(P) is m
2d5b0 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65  anaged by SQLite
2d5c0 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d   and is.** autom
2d5d0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77  atically freed w
2d5e0 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
2d5f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2d600 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65  nalized..** ^The
2d610 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2d620 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61   by sqlite3_expa
2d630 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20  nded_sql(P), on 
2d640 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a  the other hand,.
2d650 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  ** is obtained f
2d660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2d670 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20  loc()] and must 
2d680 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61  be free by the a
2d690 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79  pplication.** by
2d6a0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
2d6b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2d6c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2d6d0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
2d6e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d6f0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
2d700 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2d710 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d730 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2d740 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2d750 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2d760 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2d770 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2d780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d790 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2d7a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d7b0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2d7c0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2d7d0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2d7e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2d7f0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2d800 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2d810 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2d820 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2d830 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2d840 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2d850 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d860 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2d870 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2d880 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2d890 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2d8a0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2d8b0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2d8c0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2d8d0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2d8e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2d8f0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2d900 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2d910 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2d920 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2d930 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2d940 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2d950 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2d960 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2d970 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2d980 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2d990 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2d9a0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2d9b0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2d9c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2d9d0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2d9e0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2d9f0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2da00 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2da10 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2da20 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2da30 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2da40 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2da50 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2da60 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2da70 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2da80 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2da90 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2daa0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2dab0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2dac0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2dad0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2dae0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2daf0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2db00 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2db10 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2db20 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2db30 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2db40 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2db50 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2db60 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2db70 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2db80 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2db90 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2dba0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2dbb0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2dbc0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2dbd0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2dbe0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2dbf0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2dc00 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2dc10 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2dc20 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2dc30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2dc40 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2dc50 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2dc60 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2dc70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2dc80 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65  on disk..** ^The
2dc90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2dca0 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61  adonly() interfa
2dcb0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2dcc0 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63  for [BEGIN] sinc
2dcd0 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72  e.** [BEGIN] mer
2dce0 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61  ely sets interna
2dcf0 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65  l flags, but the
2dd00 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d   [BEGIN|BEGIN IM
2dd10 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20  MEDIATE] and.** 
2dd20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43  [BEGIN|BEGIN EXC
2dd30 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73  LUSIVE] commands
2dd40 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61   do touch the da
2dd50 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a  tabase and so.**
2dd60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2dd70 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73  adonly() returns
2dd80 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65   false for those
2dd90 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e   commands..*/.in
2dda0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
2ddb0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
2ddc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2ddd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2dde0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
2ddf0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2de00 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
2de10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2de20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2de30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2de40 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
2de50 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2de60 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
2de70 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2de80 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
2de90 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
2dea0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
2deb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2dec0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
2ded0 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
2dee0 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
2def0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
2df00 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
2df10 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
2df20 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
2df30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2df40 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
2df50 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2df60 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2df70 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
2df80 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
2df90 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
2dfa0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
2dfb0 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
2dfc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
2dfd0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
2dfe0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2dff0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
2e000 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2e010 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2e020 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
2e030 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2e040 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
2e050 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
2e060 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2e070 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
2e080 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
2e090 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
2e0a0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
2e0b0 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
2e0c0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
2e0d0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
2e0e0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
2e0f0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
2e100 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
2e110 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
2e120 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
2e130 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
2e140 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
2e150 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
2e160 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
2e170 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2e180 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2e190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e1a0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2e1b0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2e1c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2e1d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e1e0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2e1f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e200 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2e210 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2e220 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2e230 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2e240 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2e250 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2e260 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2e270 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2e280 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2e290 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2e2a0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2e2b0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2e2c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e2d0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2e2e0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2e2f0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2e300 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2e310 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2e320 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e330 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2e340 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2e350 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2e360 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2e370 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2e380 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e390 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2e3a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2e3b0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2e3c0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2e3d0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2e3e0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2e3f0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2e400 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2e410 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2e420 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2e430 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2e440 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2e450 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e460 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2e470 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2e480 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2e490 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2e4a0 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2e4b0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2e4c0 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2e4d0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2e4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2e4f0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2e500 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2e510 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2e520 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2e530 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2e540 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2e550 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2e560 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2e570 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e580 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2e590 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2e5a0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2e5b0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e5c0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2e5d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2e5e0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2e5f0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2e600 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2e610 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2e620 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2e630 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2e640 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2e650 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2e660 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2e670 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2e680 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2e690 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2e6a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2e6b0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2e6c0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2e6d0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2e6e0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2e6f0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e700 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e710 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2e720 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2e730 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2e740 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2e750 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2e760 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2e770 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2e780 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2e790 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2e7a0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2e7b0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2e7c0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2e7d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e7e0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2e7f0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2e800 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2e810 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e820 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2e830 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2e840 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2e850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e860 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2e870 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2e880 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2e890 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2e8a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2e8b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2e8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2e8d0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2e8e0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2e8f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e900 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2e910 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73   only be used as
2e920 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
2e930 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2e940 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69  _value()], [sqli
2e950 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2e960 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2e970 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
2e980 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2e990 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2e9a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2e9b0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2e9c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2e9d0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2e9e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e9f0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2ea00 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2ea10 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
2ea20 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2ea30 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2ea40 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2ea50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2ea60 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2ea70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2ea80 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2ea90 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2eaa0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2eab0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2eac0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2ead0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2eae0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2eaf0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2eb00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2eb10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2eb20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2eb30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2eb40 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2eb50 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2eb60 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2eb70 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2eb80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2eb90 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2eba0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2ebb0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2ebc0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2ebd0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2ebe0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2ebf0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2ec00 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2ec10 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2ec20 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2ec30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2ec40 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2ec50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2ec60 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2ec70 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2ec80 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2ec90 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2eca0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2ecb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2ecc0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2ecd0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2ece0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2ecf0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2ed00 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2ed10 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2ed20 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2ed30 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2ed40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ed50 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2ed60 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2ed70 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2ed80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ed90 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2eda0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2edb0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2edc0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2edd0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2ede0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2edf0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2ee00 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2ee10 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2ee20 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2ee30 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2ee40 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2ee50 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2ee60 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2ee70 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2ee80 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2ee90 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2eea0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2eeb0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2eec0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2eed0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2eee0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2eef0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2ef00 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2ef10 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2ef20 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2ef30 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2ef40 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ef50 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2ef60 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2ef70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2ef80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2ef90 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2efa0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2efb0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2efc0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2efd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2efe0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2eff0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2f000 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2f010 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2f020 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2f030 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2f040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2f050 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2f060 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2f070 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2f080 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2f090 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2f0a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2f0b0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2f0c0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2f0d0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2f0e0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2f0f0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2f100 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2f110 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2f120 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2f130 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2f140 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2f150 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2f160 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f170 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2f180 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2f190 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2f1a0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2f1b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2f1c0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2f1d0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2f1e0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2f1f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2f200 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2f210 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2f220 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2f230 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2f240 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2f250 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2f260 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2f270 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2f280 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2f290 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f2a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2f2b0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2f2c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2f2d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2f2e0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2f2f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2f300 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2f310 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2f320 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2f330 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2f340 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2f350 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2f360 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2f370 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2f380 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2f390 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2f3a0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2f3b0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2f3c0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2f3d0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2f3e0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2f3f0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2f400 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2f410 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2f420 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2f430 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2f440 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2f450 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2f460 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2f470 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2f480 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2f490 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2f4a0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2f4b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f4c0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2f4d0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2f4e0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2f4f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f500 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2f510 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2f520 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2f530 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2f540 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2f550 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2f560 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2f570 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2f580 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2f590 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2f5a0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2f5b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2f5c0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2f5d0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2f5e0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2f5f0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2f600 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2f610 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2f620 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2f630 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2f640 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2f650 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2f660 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2f670 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2f680 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2f690 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2f6a0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2f6b0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2f6c0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2f6d0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2f6e0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2f6f0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2f700 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2f710 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2f720 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2f730 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2f740 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2f750 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2f760 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2f770 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2f780 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2f790 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2f7a0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2f7b0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2f7c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2f7d0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2f7e0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2f7f0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2f800 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2f810 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2f820 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2f830 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2f840 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2f850 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2f860 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2f870 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2f880 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2f890 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2f8a0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2f8b0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2f8c0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2f8d0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2f8e0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2f8f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2f900 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2f910 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2f920 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2f930 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2f940 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2f950 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2f960 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2f970 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f980 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2f990 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2f9a0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2f9b0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f9c0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2f9d0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2f9e0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2f9f0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2fa00 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2fa10 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2fa20 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2fa30 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2fa40 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2fa50 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2fa60 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2fa70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2fa80 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2fa90 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2faa0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2fab0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2fac0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2fad0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2fae0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2faf0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2fb00 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2fb10 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2fb20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2fb30 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2fb40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fb50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2fb60 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2fb70 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2fb80 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2fb90 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2fba0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2fbb0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2fbc0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2fbd0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2fbe0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2fbf0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2fc00 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2fc10 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2fc20 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2fc30 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2fc40 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2fc50 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2fc60 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2fc70 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2fc80 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2fc90 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2fca0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2fcb0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2fcc0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2fcd0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2fce0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2fcf0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OB..**.** ^The s
2fd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2fd10 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72  ter(S,I,P,T,D) r
2fd20 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68  outine causes th
2fd30 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e I-th parameter
2fd40 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   in.** [prepared
2fd50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
2fd60 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c   have an SQL val
2fd70 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20  ue of NULL, but 
2fd80 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73  to also be.** as
2fd90 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2fda0 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74  e pointer P of t
2fdb0 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69  ype T.  ^D is ei
2fdc0 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
2fdd0 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e  ter or.** a poin
2fde0 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
2fdf0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
2fe00 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c   P. ^SQLite will
2fe10 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64   invoke the.** d
2fe20 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
2fe30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2fe40 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20  nt of P when it 
2fe50 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  is finished usin
2fe60 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70  g.** P.  The T p
2fe70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
2fe80 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69  be a static stri
2fe90 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61  ng, preferably a
2fea0 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72   string.** liter
2feb0 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f  al. The sqlite3_
2fec0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
2fed0 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f  outine is part o
2fee0 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65  f the.** [pointe
2fef0 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66  r passing interf
2ff00 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53  ace] added for S
2ff10 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a  QLite 3.20.0..**
2ff20 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2ff30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ff40 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2ff50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2ff60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2ff70 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2ff80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2ff90 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2ffa0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2ffb0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2ffc0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2ffd0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2ffe0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2fff0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
30000 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
30010 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
30020 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
30030 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
30040 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
30050 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
30060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
30070 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
30080 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
30090 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
300a0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
300b0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
300c0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
300d0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
300e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
300f0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
30100 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
30110 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
30120 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
30130 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
30140 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
30150 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
30160 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
30170 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
30180 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
30190 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
301a0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
301b0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
301c0 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
301d0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
301e0 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
301f0 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
30200 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
30210 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
30220 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
30230 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
30240 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
30250 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
30260 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
30270 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
30280 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
30290 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
302a0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
302b0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
302c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
302d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
302e0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
302f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30300 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
30310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
30320 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
30330 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30340 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
30350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30360 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
30370 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
30380 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
30390 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
303a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
303b0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
303c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
303d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
303e0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
303f0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
30400 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
30410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30420 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
30430 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
30440 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30450 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
30460 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
30470 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
30480 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
30490 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
304a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
304b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
304c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
304d0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
304e0 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
304f0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
30500 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30510 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
30520 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
30530 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
30540 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
30550 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
30560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30570 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30580 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
30590 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
305a0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
305b0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
305c0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
305d0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
305e0 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
305f0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
30600 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30610 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
30620 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
30630 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
30640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30650 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73  int, void*, cons
30660 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28  t char*,void(*)(
30670 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
30680 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
30690 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
306a0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
306b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
306c0 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
306d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
306e0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
306f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30700 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
30710 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
30720 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30730 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
30740 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
30750 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
30760 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
30770 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
30780 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30790 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
307a0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
307b0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
307c0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
307d0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
307e0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
307f0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
30800 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
30810 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
30820 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
30830 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
30840 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
30850 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
30860 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
30870 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
30880 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
30890 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
308a0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
308b0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
308c0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
308d0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
308e0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
308f0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
30900 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
30910 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
30920 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
30930 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
30940 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
30950 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
30960 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
30970 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
30980 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
30990 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
309a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
309b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
309c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
309d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
309e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
309f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
30a00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
30a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30a20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
30a30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
30a40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30a60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30a70 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
30a80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
30a90 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
30aa0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
30ab0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
30ac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ad0 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
30ae0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
30af0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
30b00 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
30b10 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
30b20 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
30b30 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
30b40 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
30b50 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
30b60 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
30b70 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
30b80 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
30b90 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
30ba0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
30bb0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
30bc0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
30bd0 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
30be0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
30bf0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
30c00 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
30c10 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
30c20 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
30c30 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
30c40 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
30c50 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
30c60 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
30c70 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
30c80 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
30c90 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
30ca0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
30cb0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
30cc0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
30cd0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
30ce0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
30cf0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
30d00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
30d10 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
30d20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
30d30 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
30d40 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
30d50 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
30d60 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
30d70 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
30d80 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73  pare16()],.** [s
30d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30da0 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  _v2()], or [sqli
30db0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
30dc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
30dd0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
30de0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30df0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
30e00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30e10 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
30e20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
30e30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
30e40 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
30e50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
30e60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30e70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30e80 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
30e90 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
30ea0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
30eb0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
30ec0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30ed0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
30ee0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
30ef0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
30f00 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
30f10 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
30f20 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
30f30 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
30f40 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
30f50 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
30f60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
30f70 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30f80 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
30f90 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
30fa0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
30fb0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
30fc0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
30fd0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
30fe0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
30ff0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
31000 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
31010 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
31020 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
31030 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
31040 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
31050 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
31060 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
31070 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31080 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
31090 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
310a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
310b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
310c0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
310d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
310e0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e  rameter_name()].
310f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31100 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
31110 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
31120 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
31130 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
31140 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
31150 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
31160 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
31170 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
31180 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31190 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
311a0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
311b0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
311c0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
311d0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
311e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
311f0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
31200 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31210 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
31220 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
31230 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
31240 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
31250 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
31260 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
31270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
31280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31290 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
312a0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
312b0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
312c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
312d0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
312e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
312f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
31300 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
31310 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
31320 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74  tatement]. ^If t
31330 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
31340 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e  rns 0, that mean
31350 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61  s the .** [prepa
31360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72  red statement] r
31370 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28  eturns no data (
31380 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
31390 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f  UPDATE])..** ^Ho
313a0 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61  wever, just beca
313b0 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
313c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
313d0 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20  ive number does 
313e0 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  not.** mean that
313f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77   one or more row
31400 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62  s of data will b
31410 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20  e returned.  ^A 
31420 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
31430 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
31440 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20  have a positive 
31450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31460 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e  ount() but depen
31470 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57  ding on the.** W
31480 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
31490 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20  traints and the 
314a0 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69  table content, i
314b0 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e  t might return n
314c0 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  o rows..**.** Se
314d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
314e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
314f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
31500 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
31510 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
31520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31530 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
31540 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
31550 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31560 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
31570 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
31580 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
31590 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
315a0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
315b0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
315c0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
315d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
315e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
315f0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
31600 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
31610 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
31620 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
31630 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
31640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31650 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
31660 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
31670 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
31680 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
31690 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
316a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
316b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
316c0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
316d0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
316e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
316f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31700 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
31710 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
31720 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
31730 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
31740 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
31750 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
31760 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
31770 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
31780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31790 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
317a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
317b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
317c0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
317d0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
317e0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
317f0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
31800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31810 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
31820 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
31830 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
31840 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
31850 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
31860 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
31870 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
31880 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
31890 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
318a0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
318b0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
318c0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
318d0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
318e0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
318f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
31900 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
31910 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
31920 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
31930 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
31940 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
31950 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
31960 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
31970 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
31980 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
31990 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
319a0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
319b0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
319c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
319d0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
319e0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
319f0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
31a00 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
31a10 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
31a20 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
31a30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
31a40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
31a50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
31a60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
31a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31a80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31a90 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
31aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
31ab0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
31ac0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
31ad0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31ae0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31af0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
31b00 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
31b10 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
31b20 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
31b30 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
31b40 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
31b50 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
31b60 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
31b70 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
31b80 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
31b90 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
31ba0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
31bb0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
31bc0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
31bd0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
31be0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
31bf0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
31c00 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
31c10 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
31c20 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
31c30 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
31c40 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
31c50 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
31c60 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
31c70 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
31c80 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
31c90 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31ca0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
31cb0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
31cc0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
31cd0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
31ce0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31cf0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
31d00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31d10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
31d20 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
31d30 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
31d40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31d50 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
31d60 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
31d70 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
31d80 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
31d90 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
31da0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
31db0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
31dc0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
31dd0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
31de0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
31df0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
31e00 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
31e10 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
31e20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
31e30 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
31e40 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
31e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31e60 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
31e70 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
31e80 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
31e90 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
31ea0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
31eb0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
31ec0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
31ed0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
31ee0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
31ef0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
31f00 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
31f10 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
31f20 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
31f30 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
31f40 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
31f50 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
31f60 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
31f70 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
31f80 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
31f90 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
31fa0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31fb0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
31fc0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
31fd0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
31fe0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
31ff0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
32000 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
32010 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
32020 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
32030 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
32040 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
32050 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
32060 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
32070 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
32080 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
32090 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
320a0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
320b0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
320c0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
320d0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
320e0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
320f0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
32100 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
32110 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
32120 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
32130 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
32140 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
32150 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
32160 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
32170 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
32180 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
32190 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
321a0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
321b0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
321c0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
321d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
321e0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
321f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
32200 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
32210 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
32220 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
32230 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
32240 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
32250 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
32260 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
32270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
32280 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
32290 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
322a0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
322b0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
322c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
322d0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
322e0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
322f0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
32300 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
32310 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
32320 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32330 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32340 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
32350 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
32360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32370 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
32380 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
32390 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
323a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
323b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
323c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
323d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
323e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
323f0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
32400 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32410 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
32420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
32430 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
32440 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
32450 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32460 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
32470 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
32480 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
32490 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
324a0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
324b0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
324c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
324d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
324e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
324f0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
32500 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
32510 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
32520 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
32530 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
32540 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
32550 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
32560 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
32570 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
32580 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
32590 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
325a0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
325b0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
325c0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
325d0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
325e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
325f0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
32600 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
32610 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
32620 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
32630 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
32640 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
32650 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
32660 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
32670 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
32680 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
32690 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
326a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
326b0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
326c0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
326d0 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
326e0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
326f0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
32700 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
32710 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
32720 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
32730 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
32740 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
32750 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
32760 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
32770 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
32780 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
32790 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
327a0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
327b0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
327c0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
327d0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
327e0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
327f0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
32800 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
32810 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
32820 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
32830 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
32840 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
32850 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
32860 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
32870 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
32880 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
32890 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
328a0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
328b0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
328c0 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
328d0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
328e0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
328f0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
32900 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
32910 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
32920 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
32930 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
32940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
32950 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
32960 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32970 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32980 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
32990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
329a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
329b0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
329c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
329d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
329e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
329f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32a00 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
32a10 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
32a20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  any of.** [sqlit
32a30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
32a40 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32a50 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
32a60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32a70 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
32a80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
32a90 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
32aa0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
32ab0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
32ac0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
32ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32ae0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
32af0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
32b00 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
32b10 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
32b20 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
32b30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
32b40 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
32b50 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
32b60 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
32b70 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
32b80 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
32b90 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
32ba0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
32bb0 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  er "vX" interfac
32bc0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  es.** [sqlite3_p
32bd0 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32be0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32bf0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32c00 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a  repare16_v3()],.
32c10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32c20 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
32c30 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
32c40 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
32c50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
32c60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
32c70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
32c80 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
32c90 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61  new "vX" interfa
32ca0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
32cb0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
32cc0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
32cd0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
32ce0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
32cf0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
32d00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
32d10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
32d20 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
32d30 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
32d40 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
32d50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
32d60 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
32d70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
32d80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
32d90 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
32da0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
32db0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
32dc0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
32dd0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
32de0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
32df0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
32e00 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
32e10 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
32e20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
32e30 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
32e40 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
32e50 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
32e60 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
32e70 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
32e80 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
32e90 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
32ea0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
32eb0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
32ec0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
32ed0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
32ee0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
32ef0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
32f00 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
32f10 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
32f20 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
32f30 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
32f40 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
32f50 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
32f60 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
32f70 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
32f80 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
32f90 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
32fa0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
32fb0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
32fc0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
32fd0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
32fe0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32ff0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
33000 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
33010 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
33020 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
33030 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
33040 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
33050 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
33060 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
33070 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
33080 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
33090 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
330a0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
330b0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
330c0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
330d0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
330e0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
330f0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
33100 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
33110 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
33120 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
33130 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
33140 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
33150 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
33160 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
33170 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
33180 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
33190 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
331a0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
331b0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
331c0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
331d0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
331e0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
331f0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
33200 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
33210 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
33220 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
33230 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
33240 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
33250 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
33260 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
33270 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
33280 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
33290 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
332a0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
332b0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
332c0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
332d0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
332e0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
332f0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
33300 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
33310 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
33320 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
33330 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
33340 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
33350 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
33360 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
33370 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
33380 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
33390 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
333a0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
333b0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
333c0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
333d0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
333e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
333f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
33400 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
33410 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
33420 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
33430 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
33440 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
33450 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
33460 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
33470 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
33480 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
33490 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
334a0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
334b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
334c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
334d0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
334e0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
334f0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33510 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
33520 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
33530 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
33540 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
33550 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
33560 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
33570 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
33580 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
33590 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
335a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
335b0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
335c0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
335d0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
335e0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
335f0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
33600 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
33610 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
33620 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
33630 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
33640 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
33650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
33660 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
33670 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
33680 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
33690 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
336a0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
336b0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
336c0 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
336d0 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
336e0 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
336f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
33700 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
33710 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
33720 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
33730 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
33740 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
33750 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
33760 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
33770 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
33780 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
33790 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
337a0 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
337b0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
337c0 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
337d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
337e0 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
337f0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
33800 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
33810 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
33820 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
33830 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
33840 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
33850 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
33860 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
33870 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
33880 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
33890 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
338a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
338b0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
338c0 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
338d0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
338e0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
338f0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
33900 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
33910 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
33920 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
33930 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
33940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
33950 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
33960 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
33970 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
33980 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
33990 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
339a0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
339b0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
339c0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
339d0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
339e0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
339f0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
33a00 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
33a10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
33a20 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
33a30 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
33a40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
33a50 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
33a60 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
33a70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33a80 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  are_v2()].** or 
33a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33aa0 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  16_v2()] or [sql
33ab0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
33ac0 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  3()] instead.** 
33ad0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
33ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
33af0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
33b00 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
33b10 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
33b20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
33b30 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
33b40 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
33b50 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
33b60 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
33b70 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22   use of the "vX"
33b80 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72   interfaces is r
33b90 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
33ba0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
33bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33bd0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
33be0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
33bf0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
33c00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33c10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
33c20 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
33c30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
33c40 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
33c50 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
33c60 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
33c70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
33c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33c90 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
33ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33cb0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
33cc0 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
33cd0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
33ce0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
33cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
33d00 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
33d10 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
33d20 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
33d30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33d40 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
33d50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33d60 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
33d70 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
33d80 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
33d90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
33da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33db0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
33dc0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
33dd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
33de0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
33df0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
33e00 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
33e10 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
33e20 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
33e30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
33e40 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
33e50 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
33e60 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
33e70 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
33e80 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
33e90 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
33ea0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
33eb0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
33ec0 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
33ed0 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
33ee0 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
33ef0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
33f00 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
33f10 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
33f20 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
33f30 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
33f40 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
33f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
33f60 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
33f70 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
33f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33f90 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
33fa0 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
33fb0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
33fc0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
33fd0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
33fe0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
33ff0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
34000 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
34010 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
34020 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
34030 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
34040 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
34050 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
34060 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
34070 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
34080 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
34090 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
340a0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
340b0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
340c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
340d0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
340e0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
340f0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
34100 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
34110 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
34120 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
34130 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
34140 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
34150 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
34160 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
34170 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
34180 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
34190 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
341a0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
341b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
341c0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
341d0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
341e0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
341f0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
34200 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
34210 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
34220 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
34230 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
34240 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
34250 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
34260 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
34270 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
34280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34290 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
342a0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
342b0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
342c0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
342d0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
342e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
342f0 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62  * <b>Summary:</b
34300 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  >.** <blockquote
34310 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30  ><table border=0
34320 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63   cellpadding=0 c
34330 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a  ellspacing=0>.**
34340 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c  te3_column_blob<
34360 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34370 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20  >BLOB result.** 
34380 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34390 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
343a0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
343b0 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a  d>REAL result.**
343c0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
343d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f  te3_column_int</
343e0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
343f0 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72  32-bit INTEGER r
34400 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
34410 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34420 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e  mn_int64</b><td>
34430 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74  &rarr;<td>64-bit
34440 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
34450 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34470 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
34480 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65  td>UTF-8 TEXT re
34490 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
344a0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
344b0 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e  n_text16</b><td>
344c0 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36  &rarr;<td>UTF-16
344d0 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20   TEXT result.** 
344e0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
344f0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c  e3_column_value<
34500 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34510 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61  >The result as a
34520 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  n .** [sqlite3_v
34530 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64  alue|unprotected
34540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34550 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c  object..** <tr><
34560 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62  td>&nbsp;<td>&nb
34570 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a  sp;<td>&nbsp;.**
34580 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
345a0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
345b0 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  d>Size of a BLOB
345c0 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54  .** or a UTF-8 T
345d0 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79  EXT result in by
345e0 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  tes.** <tr><td><
345f0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34600 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e  _bytes16&nbsp;&n
34610 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e  bsp;</b>.** <td>
34620 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73  &rarr;&nbsp;&nbs
34630 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54  p;<td>Size of UT
34640 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20  F-16.** TEXT in 
34650 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  bytes.** <tr><td
34660 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34670 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26  mn_type</b><td>&
34680 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74  rarr;<td>Default
34690 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20  .** datatype of 
346a0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f  the result.** </
346b0 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  table></blockquo
346c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74  te>.**.** <b>Det
346d0 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ails:</b>.**.** 
346e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
346f0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
34700 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
34710 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
34720 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
34730 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
34740 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
34750 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
34760 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
34770 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
34780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34790 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
347a0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
347b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
347c0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
347d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
347e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
347f0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
34800 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
34810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
34820 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
34830 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
34840 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
34850 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
34860 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
34870 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
34880 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
34890 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
348a0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
348b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
348c0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
348d0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
348e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
348f0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
34900 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
34910 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
34920 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
34930 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
34940 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
34950 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
34960 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
34970 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
34980 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
34990 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
349a0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
349b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
349c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
349d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
349e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
349f0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
34a00 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
34a10 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
34a20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34a30 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
34a40 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
34a50 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
34a60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34a70 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
34a80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34a90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
34aa0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
34ab0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
34ac0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
34ad0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
34ae0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
34af0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
34b00 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
34b10 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
34b20 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
34b30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
34b40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34b50 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
34b60 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
34b70 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
34b80 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
34b90 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
34ba0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
34bb0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
34bc0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
34bd0 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65  e first six inte
34be0 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f  rfaces (_blob, _
34bf0 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69  double, _int, _i
34c00 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64  nt64, _text, and
34c10 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63   _text16).** eac
34c20 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c  h return the val
34c30 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  ue of a result c
34c40 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69  olumn in a speci
34c50 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e  fic data format.
34c60 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75    If.** the resu
34c70 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74  lt column is not
34c80 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68   initially in th
34c90 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d  e requested form
34ca0 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  at (for example,
34cb0 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79  .** if the query
34cc0 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
34cd0 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69  ger but the sqli
34ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
34cf0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ) interface.** i
34d00 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  s used to extrac
34d10 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65  t the value) the
34d20 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74  n an automatic t
34d30 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ype conversion i
34d40 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a  s performed..**.
34d50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34d60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
34d70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34d80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
34d90 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
34da0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
34db0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
34dc0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
34dd0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
34de0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
34df0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34e00 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
34e10 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
34e20 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
34e30 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
34e40 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20  QLITE_NULL]..** 
34e50 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
34e60 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
34e70 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65  mn_type() can be
34e80 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20   used to decide 
34e90 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20  which.** of the 
34ea0 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66  first six interf
34eb0 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73  ace should be us
34ec0 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68  ed to extract th
34ed0 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a  e column value..
34ee0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
34ef0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
34f00 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
34f10 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
34f20 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d  l if no.** autom
34f30 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72  atic type conver
34f40 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
34f50 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75  red for the valu
34f60 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20  e in question.  
34f70 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65  .** After a type
34f80 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65   conversion, the
34f90 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69   result of calli
34fa0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ng sqlite3_colum
34fb0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75  n_type().** is u
34fc0 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68  ndefined, though
34fd0 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75   harmless.  Futu
34fe0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
34ff0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
35000 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
35010 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
35020 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
35030 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
35040 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
35050 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
35060 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58   a BLOB or a TEX
35070 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  T string, then t
35080 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
35090 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20  n_bytes().** or 
350a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
350b0 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61  ytes16() interfa
350c0 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ces can be used 
350d0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
350e0 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74   size.** of that
350f0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
35100 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
35110 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
35120 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
35130 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
35140 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
35150 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35160 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
35170 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
35180 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
35190 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
351a0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
351b0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
351c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
351d0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
351e0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
351f0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
35200 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35210 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
35220 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
35230 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
35240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35250 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
35260 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
35270 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
35280 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
35290 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
352a0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
352b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
352c0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
352d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
352e0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
352f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35300 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
35310 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
35320 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
35330 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
35340 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
35350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35360 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
35370 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
35380 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
35390 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
353a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
353b0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
353c0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
353d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
353e0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
353f0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
35400 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
35410 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
35420 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
35430 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35440 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
35450 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
35460 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35470 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
35480 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
35490 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
354a0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
354b0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
354c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
354d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
354e0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
354f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
35500 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
35510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35520 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
35530 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
35540 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
35550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35560 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
35570 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
35580 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
35590 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
355a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
355b0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
355c0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
355d0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
355e0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
355f0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
35600 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
35610 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
35620 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
35630 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
35640 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
35650 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
35660 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
35670 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
35680 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
35690 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
356a0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
356b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
356c0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
356d0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
356e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
356f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
35700 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
35710 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
35720 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
35730 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
35740 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35750 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
35760 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
35770 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
35780 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35790 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
357a0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
357b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
357c0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
357d0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
357e0 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
357f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35800 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
35810 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
35820 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
35830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
35840 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
35850 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35860 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
35870 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35880 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35890 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
358a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
358b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
358c0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
358d0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
358e0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
358f0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
35900 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
35910 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35920 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
35930 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
35940 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
35950 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
35960 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74  afe..** Hence, t
35970 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
35980 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  n_value() interf
35990 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c  ace.** is normal
359a0 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77  ly only useful w
359b0 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d  ithin the implem
359c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20  entation of .** 
359d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
359e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
359f0 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ns] or [virtual 
35a00 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74  tables], not wit
35a10 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  hin.** top-level
35a20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
35a30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65  e..**.** The the
35a40 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
35a50 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
35a60 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20  rt the datatype 
35a70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  of the result..*
35a80 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  * ^For example, 
35a90 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
35aa0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
35ab0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
35ac0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
35ad0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
35ae0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
35af0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
35b00 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
35b10 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
35b20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
35b30 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
35b40 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
35b50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
35b60 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
35b70 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
35b80 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
35b90 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
35ba0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
35bb0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
35bc0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
35bd0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
35be0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
35bf0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
35c00 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
35c10 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
35c20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35c30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35c40 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
35c50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
35c60 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
35c70 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
35c80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35c90 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
35ca0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
35cb0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
35cc0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
35cd0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
35ce0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
35cf0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
35d00 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
35d10 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
35d20 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
35d30 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
35d40 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
35d50 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
35d60 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
35d70 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
35d80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
35d90 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
35da0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
35db0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
35dc0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
35dd0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
35de0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
35df0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35e00 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
35e10 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
35e20 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
35e30 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
35e40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
35e50 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
35e60 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35e70 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35e80 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
35e90 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
35ea0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
35eb0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
35ec0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
35ed0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
35ee0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
35ef0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
35f00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35f10 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
35f20 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
35f30 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
35f40 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
35f50 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
35f60 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
35f70 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
35f80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
35f90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
35fa0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
35fb0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
35fc0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
35fd0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
35fe0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
35ff0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36000 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
36010 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
36020 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
36030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36040 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
36050 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
36060 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
36070 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36080 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
36090 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
360a0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
360b0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
360c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
360d0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
360e0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
360f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
36100 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
36110 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
36120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36130 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
36140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36150 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
36160 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
36170 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
36180 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
36190 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
361a0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
361b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
361c0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
361d0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
361e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
361f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
36200 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36210 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
36220 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
36230 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
36240 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
36250 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
36260 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
36270 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
36280 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
36290 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
362a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
362b0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
362c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
362d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
362e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
362f0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
36300 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
36310 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
36320 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
36330 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
36340 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
36350 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
36360 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
36370 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
36380 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
36390 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
363a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
363b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
363c0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
363d0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
363e0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
363f0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
36400 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
36410 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
36420 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
36430 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
36440 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
36450 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
36460 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
36470 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
36480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
36490 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
364a0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
364b0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
364c0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
364d0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
364e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
364f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
36500 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
36510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36520 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
36530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36540 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
36550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36560 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
36570 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
36580 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
36590 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
365a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
365b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
365c0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
365d0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
365e0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
365f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
36600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36610 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
36620 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36630 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
36640 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
36650 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
36660 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
36670 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
36680 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
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 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
366b0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
366c0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
366d0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
366e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
366f0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
36700 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
36710 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
36720 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
36730 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
36740 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
36750 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
36760 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
36770 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
36780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36790 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
367a0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
367b0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
367c0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
367d0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
367e0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
367f0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
36800 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
36810 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
36820 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36830 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
36840 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
36850 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
36860 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
36870 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
36880 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
36890 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73  ly.  Do not pass
368a0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
368b0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
368c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
368d0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
368e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
368f0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
36900 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
36910 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
36920 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
36930 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
36940 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
36950 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
36960 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
36970 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
36980 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
36990 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
369a0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
369b0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
369c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
369d0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
369e0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
369f0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
36a00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
36a10 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
36a20 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
36a30 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
36a40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36a50 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
36a60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36a70 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
36a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
36a90 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
36aa0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
36ab0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
36ac0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
36ad0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
36ae0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
36af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
36b00 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
36b10 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
36b20 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
36b30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36b40 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
36b50 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
36b60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
36b70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36b80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36b90 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
36ba0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
36bb0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
36bc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36bd0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
36be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36bf0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
36c00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
36c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36c20 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
36c30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36c40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
36c50 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
36c60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36c70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36c80 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
36c90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
36ca0 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
36cb0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
36cc0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
36cd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36ce0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36cf0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
36d00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36d10 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
36d20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
36d30 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
36d40 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
36d50 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
36d60 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
36d70 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
36d80 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
36d90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
36da0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
36db0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
36dc0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36dd0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
36de0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
36df0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
36e00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
36e10 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
36e20 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
36e30 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
36e40 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
36e50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
36e60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
36e70 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
36e80 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
36e90 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
36ea0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
36eb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36ec0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
36ed0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
36ee0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
36ef0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
36f00 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
36f10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
36f20 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
36f30 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
36f40 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
36f50 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
36f60 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
36f70 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
36f80 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
36f90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
36fa0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
36fb0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
36fc0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
36fd0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
36fe0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
36ff0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
37000 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
37010 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
37020 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
37030 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
37040 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
37050 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
37060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
37070 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
37080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37090 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
370a0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
370b0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
370c0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
370d0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
370e0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
370f0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
37100 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
37110 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
37120 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
37130 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
37140 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
37150 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
37160 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
37170 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
37180 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
37190 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
371a0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
371b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
371c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
371d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
371e0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
371f0 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
37200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37210 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
37220 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
37230 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
37240 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
37250 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
37260 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
37270 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
37280 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
37290 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
372a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
372b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
372c0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
372d0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
372e0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
372f0 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
37300 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
37310 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
37320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37330 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
37340 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
37350 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
37360 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
37370 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
37380 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
37390 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
373a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
373b0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
373c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
373d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
373e0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
373f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
37400 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
37410 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
37420 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
37430 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
37440 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
37450 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
37460 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
37470 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37480 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
37490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
374a0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
374b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
374c0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
374d0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
374e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
374f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
37500 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
37510 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
37520 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
37530 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
37540 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
37550 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
37560 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
37570 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
37580 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
37590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
375a0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
375b0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
375c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
375d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
375e0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
375f0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
37600 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
37610 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
37620 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
37630 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
37640 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
37650 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
37660 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
37670 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
37680 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
37690 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
376a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
376b0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
376c0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
376d0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
376e0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
376f0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
37700 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
37710 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
37720 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
37730 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
37740 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
37750 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
37760 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
37770 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
37780 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
37790 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
377a0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
377b0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
377c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
377d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
377e0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
377f0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
37800 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
37810 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
37820 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
37830 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
37840 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
37850 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
37860 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
37870 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
37880 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
37890 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
378a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
378b0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
378c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
378d0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
378e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
378f0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
37900 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37910 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
37920 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
37930 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
37940 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
37950 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
37960 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
37970 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
37980 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
37990 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
379a0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
379b0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
379c0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
379d0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
379e0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
379f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
37a00 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
37a10 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
37a20 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
37a30 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
37a40 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
37a50 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
37a60 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
37a70 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
37a80 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
37a90 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
37aa0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
37ab0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
37ac0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
37ad0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
37ae0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
37af0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
37b00 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
37b10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
37b20 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
37b30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
37b40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
37b50 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
37b60 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
37b70 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
37b80 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37b90 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
37ba0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
37bb0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
37bc0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
37bd0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
37be0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
37bf0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
37c00 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
37c10 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
37c20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
37c30 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
37c40 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
37c50 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
37c60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
37c70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37c80 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
37c90 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
37ca0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
37cb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
37cc0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
37cd0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
37ce0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
37cf0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
37d00 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
37d10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
37d20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37d30 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
37d40 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37d50 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
37d60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37d70 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
37d80 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
37d90 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
37da0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
37db0 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
37dc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
37dd0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
37de0 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
37df0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
37e00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37e10 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
37e20 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
37e30 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
37e40 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
37e50 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
37e60 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
37e70 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
37e80 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
37e90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
37ea0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
37eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37ec0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
37ed0 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
37ee0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
37ef0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
37f00 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
37f10 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
37f20 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
37f30 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
37f40 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
37f50 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
37f60 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
37f70 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
37f80 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
37f90 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
37fa0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
37fb0 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
37fc0 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
37fd0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
37fe0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
37ff0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
38000 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
38010 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
38020 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
38030 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
38040 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
38050 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
38060 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
38070 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
38080 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
38090 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
380a0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
380b0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
380c0 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
380d0 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
380e0 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
380f0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
38100 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
38110 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
38120 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
38130 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
38140 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
38150 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
38160 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
38170 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
38180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
38190 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
381a0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
381b0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
381c0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
381d0 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
381e0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
381f0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
38200 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
38210 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
38220 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
38230 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
38240 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
38250 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
38260 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
38270 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
38280 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
38290 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
382a0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
382b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
382c0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
382d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
382e0 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
382f0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
38300 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
38310 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
38320 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
38330 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
38340 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
38350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
38360 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
38370 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
38380 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
38390 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
383a0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
383b0 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
383c0 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
383d0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
383e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
383f0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
38400 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
38410 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
38420 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
38430 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
38440 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
38450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38460 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
38470 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
38480 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
38490 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
384a0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
384b0 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
384c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
384d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
384e0 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
384f0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
38500 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
38510 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
38520 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
38530 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
38540 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
38550 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
38560 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
38570 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
38580 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
38590 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
385a0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
385b0 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
385c0 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
385d0 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
385e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
385f0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
38600 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
38610 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
38620 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
38630 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
38640 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
38650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
38660 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
38670 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
38680 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
38690 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
386a0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
386b0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
386c0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
386d0 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
386e0 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
386f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
38700 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
38710 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
38720 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
38730 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
38740 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementa