/ Hex Artifact Content
Login

Artifact 6203acde410e38d96ffb24e9b6349f87eb80914ba5676466ac5d8478b6b8f144:


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 4c 4f 43 4b  fine SQLITE_LOCK
59f0: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5a10: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<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 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
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 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5a70: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5a90: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ab0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5ac0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5ad0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5ae0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5af0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5b00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5b10: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5b40: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5b50: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5b80: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5b90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5ba0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5bc0: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5bd0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5be0: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5bf0: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5c00: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c10: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5c20: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5c30: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c40: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5c50: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5c60: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5c70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5c90: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5cb0: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5cd0: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5cf0: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5d10: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5d30: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d50: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d70: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d90: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5da0: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5db0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5de0: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5df0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5e00: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5e10: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5e20: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5e30: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5e60: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5e70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5e80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5e90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ea0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5eb0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ec0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ee0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5ef0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5f00: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5f10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5f20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5f30: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5f40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5f50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5f60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f70: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5f80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5fb0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5fc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5fd0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ff0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
6000: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
6010: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
6020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6030: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
6040: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
6050: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6060: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6070: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6080: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6090: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
60a0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
60b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
60c0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
60d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
60e0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
60f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6100: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
6110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
6120: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
6130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6140: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
6150: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6160: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6180: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
61a0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
61c0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
61d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
61e0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
6200: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
6210: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
6220: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
6230: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
6240: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
6250: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6260: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6270: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6280: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6290: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
62a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
62b0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
62c0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
62d0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
62e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
62f0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
6300: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6310: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
6320: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6330: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
6340: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6360: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6370: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6380: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6390: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6410: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
6420: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
6430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6440: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
6450: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6460: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6480: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6490: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
64a0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
64b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64c0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
64d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
64e0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
64f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6510: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6520: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6530: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6540: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6590: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
65b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65c0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
65d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65e0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
65f0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
6600: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
6610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6620: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6630: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6640: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6650: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6660: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6670: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6680: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6690: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
66b0: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
66c0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
66d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
66f0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
6700: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6710: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6720: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6730: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6740: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6750: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6770: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6780: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6790: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
67d0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6820: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6870: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6880: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6890: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
68a0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
68b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
68c0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
68d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
68e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
68f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6900: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6910: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6930: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6940: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6950: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6960: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6970: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6980: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6990: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
69a0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
69b0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
69c0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
69d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
69e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
69f0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6a00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a10: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6a20: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6a30: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6a40: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6a50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6a70: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6a80: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6a90: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6aa0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6ab0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6ac0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6ad0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6ae0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6af0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6b00: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b10: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6b20: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6b30: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6b40: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6b50: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6b60: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6b70: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6b80: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6b90: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6ba0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6bb0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6bc0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6bd0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6be0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6bf0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6c00: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6c10: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6c20: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6c30: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6c40: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6c50: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6c60: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6c70: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6c80: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6c90: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6ca0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6cb0: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6cc0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6cd0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6ce0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6cf0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6d00: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6d10: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6d20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6d30: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6d50: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6d70: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6d80: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6d90: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6da0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6db0: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6dc0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6dd0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6de0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6df0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6e00: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6e10: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6e20: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6e30: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6e40: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6e50: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6e60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6e70: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6e80: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6e90: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6ea0: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6eb0: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6ec0: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6ed0: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6ee0: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6ef0: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6f00: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6f10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6f20: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6f30: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6f40: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6f50: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6f70: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6f80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f90: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fb0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6fc0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6fe0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ff0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7000: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
7010: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7020: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7030: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
7040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7050: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7060: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7070: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7080: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
70a0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
70b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70c0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
70d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
70e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7100: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7110: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
7140: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
7150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7160: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7170: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7180: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
71a0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
71b0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
71c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71d0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
71e0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
71f0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7200: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7210: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
7220: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7240: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
7250: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7260: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7270: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7280: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7290: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
72a0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
72b0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
72c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
72d0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
72e0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
72f0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7300: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
7310: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
7320: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7330: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
7340: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
7350: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7360: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7370: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7380: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
73a0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
73b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
73c0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
73d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
73e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
73f0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7400: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7410: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
7420: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
7430: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
7440: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
7450: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7460: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7470: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7480: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7490: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
74a0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
74b0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
74c0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
74d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
74e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
74f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7500: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
7510: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
7520: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
7530: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
7540: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
7550: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7560: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7570: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7580: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7590: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
75a0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
75b0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
75c0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
75d0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
75e0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
75f0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7600: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7610: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
7620: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
7630: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
7640: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7650: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7660: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7670: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7680: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7690: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
76a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
76b0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
76c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76d0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
76e0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76f0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7700: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7710: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
7720: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
7730: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7740: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7750: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7760: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7770: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7780: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7790: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
77a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
77b0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
77c0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
77d0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
77e0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
77f0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7800: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7810: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
7820: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
7830: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7840: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7850: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7860: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7870: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7880: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7890: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
78a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
78b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
78c0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
78d0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
78e0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
78f0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7900: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7910: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
7920: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
7930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7940: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7950: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7960: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7970: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7980: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7990: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
79a0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
79b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
79c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
79d0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
79e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
79f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7a00: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7a10: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7a20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7a30: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7a40: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7a50: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7a60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7a70: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7a80: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7a90: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7aa0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7ab0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7ac0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7ad0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7ae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7af0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7b00: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7b10: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7b20: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7b30: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7b40: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7b50: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7b60: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7b70: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7b80: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7b90: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7ba0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7bb0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7bc0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7bd0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7be0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7bf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7c00: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7c10: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7c20: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7c30: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7c40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7c50: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7c60: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c80: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7c90: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7ca0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7cd0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7ce0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7cf0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7d00: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7d10: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7d20: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7d40: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7d50: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7d60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7d70: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7d80: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7d90: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7da0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7db0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7dc0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7dd0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7de0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7e00: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7e10: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7e20: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7e30: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7e40: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7e50: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7e60: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7e70: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7e80: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7e90: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7ea0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7eb0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7ec0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7ed0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7ee0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7ef0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7f00: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7f10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7f20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7f30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7f40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7f50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7f60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7f70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7f80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7f90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7fa0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7fb0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7fc0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7fd0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7fe0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7ff0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
8000: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
8010: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
8020: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
8030: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
8040: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
8050: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8060: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8070: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8080: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8090: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
80a0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
80b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
80c0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
80d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
80e0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
80f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8100: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
8110: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8120: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
8130: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
8140: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
8150: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8160: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8170: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8180: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8190: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
81a0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
81b0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
81c0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
81d0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
81e0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
81f0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8200: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
8210: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
8220: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
8230: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
8240: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
8250: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8260: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8270: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8280: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8290: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
82a0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
82b0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
82c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
82d0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
82e0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
82f0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8300: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8310: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
8320: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
8330: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
8340: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
8350: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8360: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8370: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8380: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8390: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
83a0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
83b0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
83c0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
83d0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
83e0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
83f0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8400: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
8410: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
8420: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
8430: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
8440: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
8450: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8460: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8470: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8480: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8490: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
84a0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
84b0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
84c0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
84d0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
84e0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
84f0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8500: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
8510: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
8520: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
8530: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
8540: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
8550: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8560: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8570: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8580: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8590: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
85a0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
85b0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
85c0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
85d0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
85e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
85f0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8600: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
8610: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
8620: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
8630: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
8640: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
8650: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8660: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8670: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8680: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8690: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
86a0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
86b0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
86c0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
86d0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
86e0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
86f0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8700: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8710: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8720: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8730: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
8740: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
8750: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8760: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8770: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8780: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8790: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
87a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
87b0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
87c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
87d0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8800: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8810: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8820: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8830: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8840: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8850: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8860: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8870: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8880: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8890: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
88a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88b0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
88c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
88d0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
88e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
88f0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8900: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8910: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
8920: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
8940: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8950: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8960: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8970: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8980: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8990: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
89a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
89b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
89c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
89d0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
89e0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
89f0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8a10: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8a20: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8a30: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8a40: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8a50: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8a60: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8a70: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8a80: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8a90: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8aa0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8ac0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8ad0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8ae0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8af0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8b00: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b10: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8b20: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8b30: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8b40: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8b50: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8b70: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8b80: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8b90: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8ba0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8bb0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8bc0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8bd0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8be0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8bf0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8c00: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8c10: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8c20: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8c30: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8c40: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8c50: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8c60: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8c70: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c80: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8c90: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8ca0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8cb0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8cc0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8cd0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8ce0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8cf0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8d00: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8d10: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8d20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8d30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8d40: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8d50: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8d60: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8d80: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8d90: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8da0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8db0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8dc0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8dd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8de0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8df0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8e00: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8e10: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8e20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8e40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e60: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8e70: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8e80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8e90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8ea0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8eb0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8ec0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8ed0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8ee0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8ef0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8f00: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8f10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8f20: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8f30: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8f40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f50: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8f60: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8f70: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8f80: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f90: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8fa0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8fb0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8fc0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8fd0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8fe0: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8ff0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
9000: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
9010: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
9020: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
9030: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
9040: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9050: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9060: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9070: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9080: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9090: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
90a0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
90b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
90c0: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
90d0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
90e0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
90f0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9100: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
9110: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
9120: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
9130: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
9140: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
9150: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9160: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9170: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9180: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9190: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
91a0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
91b0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
91c0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
91d0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
91e0: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
91f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9200: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
9210: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
9220: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
9230: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
9240: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
9250: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9260: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9270: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9280: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9290: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
92a0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
92b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
92c0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
92d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
92e0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
92f0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9300: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9310: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9320: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9330: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
9340: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9350: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9360: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9370: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9390: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
93a0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
93b0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
93c0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
93d0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
93e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
93f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9400: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
9410: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
9420: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
9430: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
9440: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
9450: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9460: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9470: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9480: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9490: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
94a0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
94b0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
94c0: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
94d0: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
94e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
94f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9500: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
9520: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
9530: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
9540: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
9550: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9560: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9570: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9580: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9590: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
95a0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
95b0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
95c0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
95d0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
95e0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
95f0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9600: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9610: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
9620: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
9630: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
9640: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
9650: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9660: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9670: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9680: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
96a0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
96b0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
96c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
96d0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
96e0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
96f0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9700: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9710: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
9720: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
9730: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
9740: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9750: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9760: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9770: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9780: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9790: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
97a0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
97b0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
97c0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
97d0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
97e0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
97f0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9800: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9810: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
9820: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
9830: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9840: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9850: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9860: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9870: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9880: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9890: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
98a0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
98b0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
98c0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
98d0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
98e0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
98f0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9900: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9910: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9920: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9930: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9940: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9950: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9960: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9970: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9980: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9990: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
99a0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
99b0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
99c0: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
99d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
99e0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
99f0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9a00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9a10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
9a20: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
9a30: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
9a40: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
9a50: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9a60: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9a70: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9a80: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9a90: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9ab0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9ac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ad0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9ae0: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9af0: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9b20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9b30: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9b40: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9b50: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9b60: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9b70: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9b80: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9b90: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9ba0: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9bb0: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9bc0: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9bd0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9be0: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9bf0: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9c00: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9c10: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9c20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9c30: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9c40: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9c50: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9c60: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9c70: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9c80: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9c90: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9ca0: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9cb0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9cc0: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9cd0: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9ce0: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9cf0: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9d00: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9d10: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9d20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9d30: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9d40: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9d50: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9d60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9d70: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9d80: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9d90: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9da0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9db0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9dc0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9dd0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9de0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9df0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9e00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9e10: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9e20: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9e30: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9e40: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9e50: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9e60: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9e70: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9e80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e90: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9ea0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9eb0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9ec0: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9ed0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9ee0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9ef0: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9f00: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9f10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9f20: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9f30: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9f40: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9f50: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9f60: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9f70: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9f80: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9f90: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9fa0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9fb0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9fc0: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9fd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9fe0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9ff0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
a000: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
a010: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
a020: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
a030: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
a040: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
a070: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
a080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a090: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
a0a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a0b0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
a0c0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
a0d0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
a0e0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
a0f0: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
a100: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
a110: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
a120: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a130: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
a140: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
a150: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
a160: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
a170: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
a180: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
a190: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
a1a0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
a1b0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
a1c0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
a1d0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
a1e0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
a1f0: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
a200: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
a210: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
a220: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
a230: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
a240: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a250: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
a260: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
a270: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
a280: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
a290: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
a2a0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
a2b0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
a2c0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
a2d0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
a2e0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
a2f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a300: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
a310: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a320: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
a330: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
a340: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
a350: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
a360: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
a370: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
a380: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
a390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
a3a0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
a3b0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
a3c0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
a3d0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
a3e0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
a3f0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
a400: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
a410: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
a420: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
a430: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
a440: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
a450: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a460: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a470: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a480: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a490: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a4a0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a4c0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a4e0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a4f0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a500: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a510: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a520: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a530: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a540: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a550: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a560: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a570: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a580: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a590: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a5a0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a5b0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a5c0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a5d0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a5e0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a5f0: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a600: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a610: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a620: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a630: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a640: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a650: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a660: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a670: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a680: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a690: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a6a0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a6b0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a6c0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a6d0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a6e0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a6f0: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a700: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a710: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a720: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a730: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a740: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a750: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a760: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a770: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a780: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a790: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a7a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a7b0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a7c0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a7d0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a7e0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a7f0: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a800: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a810: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a820: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a830: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a840: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a850: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a860: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a880: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a890: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a8a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a8b0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a8c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a8d0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a8e0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a8f0: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a900: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a910: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a920: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a930: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a940: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a950: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a960: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a980: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a990: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a9a0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a9b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a9c0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a9d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a9e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a9f0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
aa00: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
aa10: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa20: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
aa30: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa40: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
aa50: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
aa60: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
aa70: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
aa80: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
aa90: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
aaa0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
aab0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
aac0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aae0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
aaf0: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
ab00: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
ab10: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
ab20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
ab30: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
ab40: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
ab50: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
ab60: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
ab70: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
ab80: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
ab90: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
aba0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
abb0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
abc0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
abd0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
abe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
abf0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
ac00: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ac10: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
ac20: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
ac30: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
ac40: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
ac50: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
ac60: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
ac70: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
ac80: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
ac90: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
aca0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
acb0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
acc0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
acd0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ace0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
acf0: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
ad00: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
ad10: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
ad20: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
ad30: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
ad40: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
ad50: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
ad60: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
ad70: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
ad80: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
ad90: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
ada0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
adb0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
adc0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
add0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
ade0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
adf0: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
ae00: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
ae10: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
ae20: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
ae30: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
ae40: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
ae50: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
ae60: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
ae70: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
ae80: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
ae90: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
aea0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
aeb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aec0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
aed0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aee0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aef0: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
af00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
af10: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
af20: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
af30: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
af40: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
af50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
af60: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
af70: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af80: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
af90: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
afa0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
afb0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
afc0: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
afd0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
afe0: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
aff0: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
b000: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
b010: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
b020: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
b030: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
b040: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
b050: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b060: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b070: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
b080: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
b090: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
b0a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
b0b0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
b0c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
b0d0: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
b0e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b0f0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
b100: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
b110: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
b120: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
b130: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
b140: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
b150: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
b160: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b170: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
b180: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
b190: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
b1a0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
b1b0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
b1c0: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
b1d0: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
b1e0: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
b1f0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
b200: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
b210: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
b220: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
b230: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
b240: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
b250: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
b260: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
b270: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b280: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
b290: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
b2a0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
b2b0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
b2c0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
b2d0: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
b2e0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b2f0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
b300: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
b310: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
b320: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
b330: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
b340: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
b350: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
b360: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
b370: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
b380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b390: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b3a0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b3b0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
b3c0: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
b3d0: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
b3e0: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
b3f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b400: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b410: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b420: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
b430: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
b440: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
b450: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b460: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b470: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b480: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b490: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b4a0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b4b0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b4c0: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b4d0: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b4e0: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b4f0: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b500: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b510: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b520: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b530: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b540: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b550: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b560: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b570: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b580: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b590: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b5a0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b5b0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b5c0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b5d0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b5e0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b5f0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b600: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b620: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b630: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b640: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b650: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b660: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b670: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b680: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b690: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b6a0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b6b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b6c0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b6d0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b6f0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b700: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b710: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b720: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b730: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b740: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b750: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b760: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b770: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b780: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b790: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b7a0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b7b0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b7c0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b7d0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b7e0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b7f0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b800: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b810: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b820: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b830: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b840: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b850: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b860: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b870: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b880: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b890: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b8a0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b8b0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b8c0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b8d0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b8e0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b8f0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b900: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b910: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b920: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b930: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b940: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b950: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b960: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b980: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b990: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b9a0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b9b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b9c0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b9d0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b9e0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b9f0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
ba00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
ba10: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
ba20: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
ba30: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
ba40: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
ba50: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
ba60: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
ba70: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ba80: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ba90: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
baa0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
bab0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
bac0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
bad0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
bae0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
baf0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
bb00: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
bb10: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
bb20: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
bb30: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
bb40: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
bb50: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
bb60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bb70: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
bb80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bb90: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
bba0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bbb0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
bbc0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
bbd0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
bbe0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
bbf0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
bc00: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
bc10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bc20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bc30: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
bc40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
bc50: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
bc60: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
bc70: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
bc80: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
bc90: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
bca0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
bcb0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
bcc0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
bcd0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
bce0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
bcf0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
bd00: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
bd10: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
bd20: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
bd30: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
bd40: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
bd50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
bd60: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
bd70: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
bd80: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
bd90: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
bda0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
bdb0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
bdc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bdd0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
bde0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bdf0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
be00: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
be10: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
be20: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
be30: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
be40: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
be50: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
be60: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
be70: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be80: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
be90: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
bea0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
beb0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
bec0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
bed0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
bee0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
bef0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
bf00: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
bf10: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bf20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
bf30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bf40: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
bf50: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bf60: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bf70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf80: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf90: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bfa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bfb0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bfc0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bfd0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bfe0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bff0: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
c000: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
c010: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
c020: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
c030: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
c040: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
c050: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
c060: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
c070: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
c080: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
c090: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c0a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c0b0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c0c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
c0e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
c0f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
c100: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
c110: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c120: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
c130: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
c140: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
c150: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c160: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c170: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c180: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c190: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
c1a0: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
c1b0: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
c1c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c1d0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c1e0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c200: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
c210: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
c220: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
c230: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
c240: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
c250: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
c260: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
c270: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
c280: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
c290: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
c2a0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
c2b0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
c2c0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
c2d0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
c2e0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
c2f0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
c300: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c310: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c320: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c330: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c340: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c350: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
c360: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
c370: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
c380: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
c390: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
c3a0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
c3b0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
c3c0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
c3d0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
c3e0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
c3f0: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
c400: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
c410: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
c420: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
c430: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
c440: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
c450: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c460: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c470: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c480: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c490: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c4a0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c4b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c4c0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c4d0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c4e0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c4f0: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c500: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c520: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c530: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c550: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c560: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c570: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c580: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c590: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c5a0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c5b0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c5c0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c5d0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c5e0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c5f0: 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  pcode.  .**.** <
c600: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c610: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c620: 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65  RITE]].** If the
c630: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c640: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c650: 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e  E] opcode return
c660: 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65  s SQLITE_OK, the
c670: 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65  n.** the file de
c680: 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63  scriptor is plac
c690: 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69  ed in "batch wri
c6a0: 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a  te mode", which.
c6b0: 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62  ** means all sub
c6c0: 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70  sequent write op
c6d0: 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  erations will be
c6e0: 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f   deferred and do
c6f0: 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79  ne.** atomically
c700: 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51   at the next [SQ
c710: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c720: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  T_ATOMIC_WRITE].
c730: 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61    Systems.** tha
c740: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  t do not support
c750: 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72   batch atomic wr
c760: 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e  ites will return
c770: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c780: 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20  ..** ^Following 
c790: 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c  a successful SQL
c7a0: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c7b0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64  ATOMIC_WRITE and
c7c0: 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65   prior to.** the
c7d0: 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45   closing [SQLITE
c7e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c7f0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a  OMIC_WRITE] or.*
c800: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c810: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c820: 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77  WRITE], SQLite w
c830: 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56  ill make.** no V
c840: 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  FS interface cal
c850: 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ls on the same [
c860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69  sqlite3_file] fi
c870: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a  le descriptor.**
c880: 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c   except for call
c890: 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20  s to the xWrite 
c8a0: 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78  method and the x
c8b0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
c8c0: 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49  od.** with [SQLI
c8d0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c8e0: 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  NT]..**.** <li>[
c8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c900: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c910: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c920: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c930: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c940: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
c950: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
c960: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
c970: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
c980: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
c990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c9a0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c9b0: 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  to be performed 
c9c0: 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54  atomically..** T
c9d0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c9e0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
c9f0: 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK] if and only
ca00: 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77   if the writes w
ca10: 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f  ere.** all perfo
ca20: 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  rmed successfull
ca30: 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20  y and have been 
ca40: 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72  committed to per
ca50: 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e  sistent storage.
ca60: 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
ca70: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
ca80: 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  t it is successf
ca90: 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f  ul, this file co
caa0: 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74  ntrol takes.** t
cab0: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cac0: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cad0: 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68  write mode so th
cae0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
caf0: 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  t.** write opera
cb00: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cb10: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cb20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cb30: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cb40: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cb50: 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20  RITE without.** 
cb60: 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
cb70: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49  ul call to [SQLI
cb80: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cb90: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a  TOMIC_WRITE]..**
cba0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cbb0: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cbc0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cbd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cbe0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cbf0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
cc00: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
cc10: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
cc20: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
cc30: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
cc40: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
cc50: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cc60: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
cc70: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  be rolled back..
cc80: 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f  ** ^This file co
cc90: 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20  ntrol takes the 
cca0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
ccb0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ccc0: 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68  te mode.** so th
ccd0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
cce0: 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t write operatio
ccf0: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
cd00: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
cd10: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cd20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
cd30: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
cd40: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cd50: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cd60: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cd70: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd80: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cd90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cda0: 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f  FCNTL_LOCK_TIMEO
cdb0: 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  UT]].** The [SQL
cdc0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
cdd0: 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63  IMEOUT] opcode c
cde0: 61 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74  auses attempts t
cdf0: 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69  o obtain.** a fi
ce00: 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68  le lock using th
ce10: 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c  e xLock or xShmL
ce20: 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ock methods of t
ce30: 68 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a  he VFS to wait.*
ce40: 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69  * for up to M mi
ce50: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
ce60: 65 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65  e failing, where
ce70: 20 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65   M is the single
ce80: 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e   .** unsigned in
ce90: 74 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e  teger parameter.
cea0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ceb0: 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
cec0: 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20  ERSION]].** The 
ced0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
cee0: 54 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f  TA_VERSION] opco
cef0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 64 65  de is used to de
cf00: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  tect changes to.
cf10: 2a 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ** a database fi
cf20: 6c 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  le.  The argumen
cf30: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
cf40: 6f 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  o a 32-bit unsig
cf50: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20  ned integer..** 
cf60: 54 68 65 20 22 64 61 74 61 20 76 65 72 73 69 6f  The "data versio
cf70: 6e 22 20 66 6f 72 20 74 68 65 20 70 61 67 65 72  n" for the pager
cf80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
cf90: 20 74 68 65 20 70 6f 69 6e 74 65 72 2e 20 20 54   the pointer.  T
cfa0: 68 65 0a 2a 2a 20 22 64 61 74 61 20 76 65 72 73  he.** "data vers
cfb0: 69 6f 6e 22 20 63 68 61 6e 67 65 73 20 77 68 65  ion" changes whe
cfc0: 6e 65 76 65 72 20 61 6e 79 20 63 68 61 6e 67 65  never any change
cfd0: 20 6f 63 63 75 72 73 20 74 6f 20 74 68 65 20 63   occurs to the c
cfe0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
cff0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 65  database file, e
d000: 69 74 68 65 72 20 74 68 72 6f 75 67 68 20 53 51  ither through SQ
d010: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
d020: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
d030: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  e.** connection,
d040: 20 6f 72 20 74 68 72 6f 75 67 68 20 74 72 61 6e   or through tran
d050: 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74 74  sactions committ
d060: 65 64 20 62 79 20 73 65 70 61 72 61 74 65 20 64  ed by separate d
d070: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
d080: 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79 20  ctions possibly 
d090: 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  in other process
d0a0: 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33  es. The [sqlite3
d0b0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
d0c0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63  ].** interface c
d0d0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
d0e0: 6e 64 20 69 66 20 61 6e 79 20 64 61 74 61 62 61  nd if any databa
d0f0: 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63  se on the connec
d100: 74 69 6f 6e 20 68 61 73 20 63 68 61 6e 67 65 64  tion has changed
d110: 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 20 69 6e  ,.** but that in
d120: 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 73 65  terface response
d130: 20 74 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20 54   to changes on T
d140: 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 73 20 4d  EMP as well as M
d150: 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a 20  AIN and does.** 
d160: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65  not provide a me
d170: 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74 65 63  chanism to detec
d180: 74 20 63 68 61 6e 67 65 73 20 74 6f 20 4d 41 49  t changes to MAI
d190: 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20 74  N only.  Also, t
d1a0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
d1b0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
d1c0: 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e  interface respon
d1d0: 73 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 63  se to internal c
d1e0: 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64 0a  hanges only and.
d1f0: 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73  ** omits changes
d200: 20 6d 61 64 65 20 62 79 20 6f 74 68 65 72 20 64   made by other d
d210: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d220: 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50 52  ons.  The.** [PR
d230: 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f  AGMA data_versio
d240: 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69  n] command provi
d250: 64 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74  de a mechanism t
d260: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d270: 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20   to.** a single 
d280: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d290: 65 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 65  e that occur due
d2a0: 20 74 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61   to other databa
d2b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a  se connections,.
d2c0: 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 63 68 61  ** but omits cha
d2d0: 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  nges implemented
d2e0: 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
d2f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 66 6f 72 20   connection for 
d300: 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a 20 63  which it is.** c
d310: 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 69 6c  alled.  This fil
d320: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65  e control is the
d330: 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20   only mechanism 
d340: 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  to detect change
d350: 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e  s that.** happen
d360: 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c   either internal
d370: 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79  ly or externally
d380: 20 6f 6e 20 61 20 73 69 6e 67 6c 65 20 64 61 74   on a single dat
d390: 61 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  abase..** </ul>.
d3a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d3b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
d3c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d3d0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d3e0: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
d3f0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d410: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
d420: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
d430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d440: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
d450: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
d460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d470: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
d480: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
d490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d4a0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
d4b0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
d4c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d4d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
d4e0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
d4f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d500: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
d510: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
d520: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d530: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
d540: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
d550: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d560: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
d570: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
d580: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
d590: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
d5a0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
d5b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
d5c0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
d5d0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
d5e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
d5f0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
d600: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
d610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d620: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
d630: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
d640: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
d650: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
d660: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
d670: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
d680: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
d690: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
d6a0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
d6b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
d6c0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d6d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
d6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
d6f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d700: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
d710: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
d720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d730: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
d740: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
d750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d760: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
d770: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
d780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d790: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
d7a0: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
d7b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d7c0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
d7d0: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
d7e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d7f0: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
d800: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
d810: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d820: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
d830: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e         26.#defin
d840: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
d850: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  FS_POINTER      
d860: 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65        27.#define
d870: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f   SQLITE_FCNTL_JO
d880: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20  URNAL_POINTER   
d890: 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20       28.#define 
d8a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d8b0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_GET_HANDLE   
d8c0: 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53      29.#define S
d8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20  QLITE_FCNTL_PDB 
d8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8f0: 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51     30.#define SQ
d900: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
d910: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20  _ATOMIC_WRITE   
d920: 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    31.#define SQL
d930: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
d940: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20  _ATOMIC_WRITE   
d950: 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
d960: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
d970: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  K_ATOMIC_WRITE  
d980: 33 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  33.#define SQLIT
d990: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d  E_FCNTL_LOCK_TIM
d9a0: 45 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33  EOUT           3
d9b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d9c0: 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
d9d0: 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35  ION           35
d9e0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
d9f0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
da00: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
da10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
da20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
da30: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
da40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
da50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
da60: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
da70: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
da80: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
da90: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
daa0: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
dab0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
dac0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
dad0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
dae0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
daf0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
db00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
db10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
db20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
db30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
db40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
db50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
db60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
db70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
db80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
db90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
dba0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
dbb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
dbc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
dbd0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
dbe0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
dbf0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
dc00: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
dc10: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
dc20: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
dc30: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
dc40: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
dc50: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
dc60: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
dc70: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
dc80: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
dc90: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
dca0: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
dcb0: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
dcc0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
dcd0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
dce0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
dcf0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
dd00: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
dd10: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
dd20: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
dd30: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
dd40: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
dd50: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
dd60: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
dd70: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
dd80: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
dd90: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
dda0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ddb0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
ddc0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
ddd0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
dde0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
ddf0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
de00: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
de10: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
de20: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
de30: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
de40: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
de50: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
de60: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
de70: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
de80: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
de90: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
dea0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
deb0: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
dec0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
ded0: 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74  *.** The VFS int
dee0: 65 72 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69  erface is someti
def0: 6d 65 73 20 65 78 74 65 6e 64 65 64 20 62 79 20  mes extended by 
df00: 61 64 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f  adding new metho
df10: 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65  ds onto.** the e
df20: 6e 64 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73  nd.  Each time s
df30: 75 63 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  uch an extension
df40: 20 6f 63 63 75 72 73 2c 20 74 68 65 20 69 56 65   occurs, the iVe
df50: 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69  rsion field.** i
df60: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20  s incremented.  
df70: 54 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  The iVersion val
df80: 75 65 20 73 74 61 72 74 65 64 20 6f 75 74 20 61  ue started out a
df90: 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65  s 1 in.** SQLite
dfa0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d   [version 3.5.0]
dfb0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e   on [dateof:3.5.
dfc0: 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73  0], then increas
dfd0: 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20  ed to 2.** with 
dfe0: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
dff0: 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f  3.7.0] on [dateo
e000: 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68  f:3.7.0], and th
e010: 65 6e 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20  en increased.** 
e020: 74 6f 20 33 20 77 69 74 68 20 53 51 4c 69 74 65  to 3 with SQLite
e030: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d   [version 3.7.6]
e040: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
e050: 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  6].  Additional 
e060: 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65  fields.** may be
e070: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65   appended to the
e080: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
e090: 65 63 74 20 61 6e 64 20 74 68 65 20 69 56 65 72  ect and the iVer
e0a0: 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61  sion value.** ma
e0b0: 79 20 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e  y increase again
e0c0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
e0d0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
e0e0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
e0f0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
e100: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
e110: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
e120: 6e 20 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e  n the transition
e130: 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20   from.** SQLite 
e140: 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20  [version 3.5.9] 
e150: 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  to [version 3.6.
e160: 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  0] on [dateof:3.
e170: 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20  6.0].** and yet 
e180: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
e190: 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66  ld was not modif
e1a0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
e1b0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
e1c0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
e1d0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
e1e0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
e1f0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
e200: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
e210: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
e220: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
e230: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
e240: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
e250: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
e260: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
e270: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
e280: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
e290: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
e2a0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
e2b0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
e2c0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
e2d0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
e2e0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
e2f0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
e300: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
e310: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
e320: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
e330: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
e340: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
e350: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
e360: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e370: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
e380: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
e390: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
e3a0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
e3b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
e3c0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
e3d0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
e3e0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
e3f0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
e400: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
e410: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
e420: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
e430: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
e440: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
e450: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
e460: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
e470: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
e480: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
e490: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
e4a0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
e4b0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
e4c0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
e4d0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
e4e0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
e4f0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
e500: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
e510: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
e520: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
e530: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
e540: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
e550: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
e560: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
e570: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
e580: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
e590: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e5a0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
e5b0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
e5c0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
e5d0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
e5e0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
e5f0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
e600: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
e610: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
e620: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
e630: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e640: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
e650: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
e660: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
e670: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
e680: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
e690: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
e6a0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
e6b0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
e6c0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
e6d0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
e6e0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
e6f0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
e700: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
e710: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
e720: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
e730: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
e740: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
e750: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
e760: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
e770: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
e780: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
e790: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
e7a0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
e7b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
e7c0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
e7d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e7e0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
e7f0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
e800: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
e810: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
e820: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
e830: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
e840: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
e850: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
e860: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
e870: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
e880: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
e890: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
e8a0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
e8b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e8c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
e8d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
e8e0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
e8f0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
e900: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
e910: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
e920: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
e930: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
e940: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
e950: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
e960: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
e970: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
e980: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
e990: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
e9a0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
e9b0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
e9c0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
e9d0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
e9e0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
e9f0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ea00: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ea10: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ea20: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
ea30: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
ea40: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
ea50: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
ea60: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
ea70: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
ea80: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
ea90: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
eaa0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
eab0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
eac0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
ead0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
eae0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
eaf0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
eb00: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
eb10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
eb20: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
eb30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
eb40: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
eb50: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
eb60: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
eb70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eb80: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
eb90: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
eba0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ebb0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ebc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ebd0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ebe0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
ebf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ec00: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
ec10: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
ec20: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
ec30: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
ec40: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
ec50: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
ec60: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
ec70: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
ec80: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
ec90: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
eca0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
ecb0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
ecc0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
ecd0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
ece0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
ecf0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
ed00: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
ed10: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
ed20: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
ed30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
ed40: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
ed50: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
ed60: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
ed70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
ed80: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
ed90: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
eda0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
edb0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
edc0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
edd0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
ede0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
edf0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
ee00: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
ee10: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
ee20: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
ee30: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
ee40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
ee50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
ee60: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
ee70: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
ee80: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
ee90: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
eea0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
eeb0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
eec0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
eed0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
eee0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
eef0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
ef00: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ef10: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
ef20: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
ef30: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
ef40: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
ef50: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
ef60: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
ef70: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
ef80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
ef90: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
efa0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
efb0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
efc0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
efd0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
efe0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
eff0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
f000: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
f010: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
f020: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
f030: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
f040: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
f050: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
f060: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
f070: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
f080: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
f090: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
f0a0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
f0b0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
f0c0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
f0d0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
f0e0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
f0f0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
f100: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
f110: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f120: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
f130: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
f140: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
f150: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
f160: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
f170: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
f180: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
f190: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
f1a0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
f1b0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
f1c0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
f1d0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
f1e0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
f1f0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
f200: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
f210: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
f220: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
f230: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
f240: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
f250: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
f260: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
f270: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
f280: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
f290: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
f2a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
f2b0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
f2c0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
f2d0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
f2e0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
f2f0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
f300: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
f310: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
f320: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
f330: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
f340: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
f350: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
f360: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
f370: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
f380: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
f390: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
f3a0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
f3b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
f3c0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
f3d0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f3e0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
f3f0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
f400: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
f410: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
f420: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
f430: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
f440: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f450: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
f460: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
f470: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
f480: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
f490: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
f4a0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
f4b0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
f4c0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
f4d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
f4e0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
f4f0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
f500: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
f510: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
f520: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
f530: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
f540: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
f550: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
f560: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
f570: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
f580: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
f590: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f5a0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
f5b0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
f5c0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
f5d0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
f5e0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
f5f0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
f600: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
f610: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
f620: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
f630: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
f640: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
f650: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
f660: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
f670: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
f680: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
f690: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
f6a0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
f6b0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
f6c0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
f6d0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
f6e0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
f6f0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
f700: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
f710: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
f720: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
f730: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
f740: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
f750: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
f760: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
f770: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
f780: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
f790: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
f7a0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
f7b0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
f7c0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
f7d0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
f7e0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
f7f0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
f800: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
f810: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
f820: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
f830: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
f840: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
f850: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
f860: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f870: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
f880: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
f890: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
f8a0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
f8b0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
f8c0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
f8d0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
f8e0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f8f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
f900: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
f910: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
f920: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
f930: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
f940: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
f950: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
f960: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
f970: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
f980: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
f990: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f9a0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
f9b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
f9c0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
f9d0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
f9e0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
f9f0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
fa00: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
fa10: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
fa20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
fa30: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
fa40: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
fa50: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
fa60: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
fa70: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
fa80: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
fa90: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
faa0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
fab0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
fac0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
fad0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
fae0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
faf0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
fb00: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
fb10: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
fb20: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
fb30: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
fb40: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
fb50: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
fb60: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
fb70: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
fb80: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
fb90: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
fba0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
fbb0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
fbc0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
fbd0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
fbe0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
fbf0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
fc00: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
fc10: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
fc20: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
fc30: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
fc40: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
fc50: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
fc60: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
fc70: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
fc80: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
fc90: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
fca0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
fcb0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
fcc0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
fcd0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
fce0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
fcf0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
fd00: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
fd10: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
fd20: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
fd30: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
fd40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
fd50: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
fd60: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
fd70: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
fd80: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
fd90: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
fda0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
fdb0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
fdc0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
fdd0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
fde0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
fdf0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
fe00: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
fe10: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
fe20: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
fe30: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
fe40: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
fe50: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
fe60: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
fe70: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
fe80: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
fe90: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
fea0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
feb0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
fec0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
fed0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
fee0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
fef0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
ff00: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
ff10: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
ff20: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ff30: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ff40: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ff50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ff60: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ff70: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ff80: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ff90: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
ffa0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
ffb0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ffc0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ffd0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
ffe0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
fff0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
10000 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
10010 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
10020 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10030 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
10040 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
10050 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
10060 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10070 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
10080 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
10090 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
100a0 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
100b0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
100c0 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
100d0 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
100e0 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
100f0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10100 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
10110 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
10120 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
10130 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
10140 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
10150 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
10160 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
10170 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
10180 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
10190 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
101a0 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
101b0 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
101c0 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
101d0 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
101e0 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
101f0 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
10200 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
10210 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
10220 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
10230 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
10240 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10250 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
10260 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
10270 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10280 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
10290 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
102a0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
102b0 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
102c0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
102d0 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
102e0 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
102f0 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
10300 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
10310 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
10320 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
10330 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
10340 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
10350 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
10360 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
10370 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
10380 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
10390 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
103a0 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
103b0 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
103c0 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
103d0 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
103e0 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
103f0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10400 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10410 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
10420 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
10430 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
10440 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
10450 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10460 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10470 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
10480 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
10490 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
104a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
104b0 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
104c0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
104d0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
104e0 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
104f0 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
10500 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
10510 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
10520 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
10530 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
10540 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
10550 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
10560 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
10570 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
10580 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
10590 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
105a0 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
105b0 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
105c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
105d0 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
105e0 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
105f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
10600 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
10610 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
10620 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
10630 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
10640 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
10650 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
10660 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
10670 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
10680 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10690 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
106a0 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
106b0 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
106c0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
106d0 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
106e0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
106f0 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
10700 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10710 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10720 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
10730 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
10740 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
10750 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
10760 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
10770 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
10780 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
10790 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
107a0 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
107b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
107c0 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
107d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
107e0 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
107f0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
10800 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
10810 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
10820 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
10830 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
10840 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
10850 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10860 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
10870 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10880 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10890 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
108a0 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
108b0 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
108c0 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
108d0 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
108e0 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
108f0 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
10900 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
10910 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
10920 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
10930 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
10940 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10950 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
10960 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
10970 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10980 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
10990 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
109a0 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
109b0 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
109c0 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
109d0 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
109e0 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
109f0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
10a00 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
10a10 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
10a20 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
10a30 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
10a40 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10a50 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
10a60 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
10a70 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
10a80 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
10a90 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
10aa0 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
10ab0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
10ac0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10ad0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10ae0 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10af0 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
10b00 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
10b10 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
10b20 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
10b30 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
10b40 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10b50 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10b60 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10b70 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10b80 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
10b90 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
10ba0 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
10bb0 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
10bc0 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
10bd0 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
10be0 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
10bf0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
10c00 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
10c10 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
10c20 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
10c30 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
10c40 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
10c50 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
10c60 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
10c70 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
10c80 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10c90 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
10ca0 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
10cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10cc0 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
10cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
10ce0 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
10cf0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
10d00 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
10d10 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
10d20 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10d30 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
10d40 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
10d50 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
10d60 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
10d70 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
10d80 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
10d90 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
10da0 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
10db0 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
10dc0 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
10dd0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
10de0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
10df0 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
10e00 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
10e10 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
10e20 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
10e30 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
10e40 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
10e50 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
10e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
10e70 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
10e80 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10e90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10ea0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10eb0 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
10ec0 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
10ed0 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
10ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10ef0 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
10f00 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
10f10 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
10f20 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
10f30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f40 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
10f50 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
10f60 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
10f70 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
10f80 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
10f90 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
10fa0 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
10fb0 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
10fc0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
10fd0 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
10fe0 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
10ff0 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
11000 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11010 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11020 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11030 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
11040 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
11050 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
11060 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11070 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
11080 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
11090 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
110a0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
110b0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
110c0 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
110d0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
110e0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
110f0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
11100 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
11110 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
11120 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
11130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11140 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
11150 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
11160 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
11170 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
11180 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
11190 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
111a0 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
111b0 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
111c0 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
111d0 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
111e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
111f0 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
11200 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11210 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
11220 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
11230 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11240 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
11250 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
11260 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
11270 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
11280 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11290 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
112a0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
112b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
112c0 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
112d0 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
112e0 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
112f0 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
11300 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
11310 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
11320 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
11330 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
11340 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
11350 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
11360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11370 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
11380 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
11390 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
113a0 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
113b0 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
113c0 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
113d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
113e0 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
113f0 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
11400 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11410 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
11420 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11430 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
11440 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
11450 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
11460 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
11470 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
11480 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11490 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
114a0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
114b0 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
114c0 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
114d0 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
114e0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
114f0 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
11500 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
11510 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
11520 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
11530 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
11540 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
11550 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
11560 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
11570 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
11580 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
11590 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
115a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
115b0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
115c0 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
115d0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
115e0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
115f0 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
11600 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
11610 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
11620 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11630 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11640 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
11650 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
11660 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
11670 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11680 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
11690 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
116a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
116b0 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
116c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
116d0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
116e0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
116f0 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
11700 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
11710 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
11720 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
11730 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
11740 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
11750 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
11760 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
11770 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
11780 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11790 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
117a0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
117b0 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
117c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
117d0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
117e0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
117f0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11800 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
11810 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
11820 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
11830 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
11840 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
11850 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
11860 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
11870 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
11880 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11890 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
118a0 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
118b0 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
118c0 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
118d0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
118e0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
118f0 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
11900 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
11910 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
11920 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
11930 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
11940 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
11950 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
11960 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
11970 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
11980 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11990 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
119a0 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
119b0 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
119c0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
119d0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
119e0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
119f0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11a00 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
11a10 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
11a20 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11a30 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
11a40 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
11a50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
11a60 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
11a70 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
11a80 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
11a90 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
11aa0 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
11ab0 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
11ac0 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
11ad0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
11ae0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
11af0 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
11b00 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
11b10 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
11b20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
11b30 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
11b40 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
11b50 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
11b60 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11b70 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
11b80 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
11b90 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
11ba0 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
11bb0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
11bc0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
11bd0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
11be0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
11bf0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
11c00 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
11c10 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
11c20 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
11c30 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
11c40 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11c50 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
11c60 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11c70 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
11c80 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
11c90 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
11ca0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11cb0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
11cc0 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
11cd0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
11ce0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
11cf0 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
11d00 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
11d10 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
11d20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
11d30 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
11d40 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
11d50 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
11d60 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
11d70 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
11d80 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
11d90 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
11da0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
11db0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11dc0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11dd0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
11de0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
11df0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
11e00 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
11e10 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
11e20 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
11e30 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
11e40 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11e50 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
11e60 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
11e70 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
11e80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11e90 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
11ea0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
11eb0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
11ec0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
11ed0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
11ee0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
11ef0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11f00 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
11f10 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
11f20 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
11f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
11f40 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
11f50 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
11f60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
11f70 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
11f80 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
11f90 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
11fa0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
11fb0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
11fc0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
11fd0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
11fe0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
11ff0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
12000 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
12010 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
12020 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
12030 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
12040 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
12050 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
12060 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
12070 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
12080 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
12090 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
120a0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
120b0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
120c0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
120d0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
120e0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
120f0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
12100 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
12110 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
12120 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
12130 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
12140 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
12150 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12160 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
12170 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
12180 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
12190 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
121a0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
121b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
121c0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
121d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
121e0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
121f0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
12200 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
12210 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12220 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
12230 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12240 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
12250 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
12260 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
12270 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
12280 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
12290 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
122a0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
122b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
122c0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
122d0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
122e0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
122f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
12300 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12310 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
12320 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
12330 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12340 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
12350 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
12360 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
12370 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
12380 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
12390 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
123a0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
123b0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
123c0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
123d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
123e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
123f0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
12400 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
12410 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12420 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12430 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
12440 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
12450 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
12460 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
12470 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
12480 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
12490 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
124a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
124b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
124c0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
124d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
124e0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
124f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
12500 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
12510 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
12520 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12530 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
12540 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
12550 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
12560 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
12570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
12580 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
12590 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
125a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
125b0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
125c0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
125d0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
12600 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12610 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** 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 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
12640 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
12650 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
12660 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12670 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
12680 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
12690 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
126a0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
126b0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
126c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
126d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
126e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
126f0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
12700 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
12710 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
12720 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
12730 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
12740 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
12750 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
12760 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
12770 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
12780 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
12790 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
127a0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
127b0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
127c0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
127d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
127e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
127f0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
12800 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12810 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
12820 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
12830 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
12840 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
12850 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12860 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
12870 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
12880 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
12890 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
128a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
128b0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
128c0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
128d0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
128e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
128f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12900 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
12910 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12920 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
12930 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
12940 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
12950 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
12960 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
12970 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12980 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
12990 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
129a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
129b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129c0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
129d0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
129e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
129f0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
12a00 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
12a10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12a20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
12a30 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
12a40 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
12a50 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
12a60 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
12a70 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
12a80 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
12a90 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
12aa0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
12ab0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
12ac0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
12ad0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
12ae0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
12af0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
12b00 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
12b10 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
12b20 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
12b30 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12b40 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
12b50 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
12b60 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
12b70 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
12b80 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
12b90 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
12ba0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
12bb0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
12bc0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
12bd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12be0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
12bf0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
12c00 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
12c10 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
12c20 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
12c30 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
12c40 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
12c50 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
12c60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
12c70 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
12c80 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
12c90 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
12ca0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
12cb0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
12cc0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
12cd0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
12ce0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
12cf0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
12d00 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
12d10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
12d20 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
12d30 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
12d40 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
12d50 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
12d60 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
12d70 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
12d80 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
12d90 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
12da0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
12db0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
12dc0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
12dd0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
12de0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
12df0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
12e00 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
12e10 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
12e20 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
12e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
12e40 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
12e50 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
12e60 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
12e70 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
12e80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
12e90 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
12ea0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
12eb0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
12ec0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
12ed0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
12ee0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
12ef0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
12f00 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
12f10 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
12f20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
12f30 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
12f40 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
12f50 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
12f60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
12f70 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
12f80 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
12f90 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
12fa0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
12fb0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
12fc0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
12fd0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
12fe0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
12ff0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
13000 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
13010 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
13020 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
13030 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
13040 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
13050 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
13060 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
13070 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
13080 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
13090 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
130a0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
130b0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
130c0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
130d0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
130e0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
130f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13100 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
13110 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
13120 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
13130 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
13140 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
13150 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
13160 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
13170 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
13180 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
13190 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
131a0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
131b0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
131c0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
131d0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
131e0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
131f0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
13200 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
13210 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
13220 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
13230 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
13240 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
13250 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
13260 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
13270 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
13280 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
13290 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
132a0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
132b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
132c0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
132d0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
132e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
132f0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13300 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13310 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
13320 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
13330 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
13340 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
13350 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
13360 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
13370 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
13380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13390 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
133a0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
133b0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
133c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
133d0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
133e0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
133f0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
13400 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
13410 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
13420 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
13430 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
13440 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
13450 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
13460 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
13470 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
13480 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
13490 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
134a0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
134b0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
134c0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
134d0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
134e0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
134f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13500 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
13510 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
13520 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
13530 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
13540 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
13550 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
13560 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
13570 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
13580 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
13590 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
135a0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
135b0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
135c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
135d0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
135e0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
135f0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
13600 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
13610 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
13620 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
13630 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13640 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
13650 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13660 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
13670 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
13680 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
13690 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
136a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
136b0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
136c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
136d0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
136e0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
136f0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
13700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13710 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13720 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
13730 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
13740 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
13750 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
13760 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
13770 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
13780 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
13790 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
137a0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
137b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
137c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
137d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
137e0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
137f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13800 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13810 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13820 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13830 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13840 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13850 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13860 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13870 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13880 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
13890 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
138a0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
138b0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
138c0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
138d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
138e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
138f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
13900 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
13910 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
13920 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
13930 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
13940 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
13950 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
13960 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
13970 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13980 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
13990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
139a0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
139b0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
139c0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
139d0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
139e0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139f0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13a00 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
13a10 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
13a20 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
13a30 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
13a40 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
13a50 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
13a60 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
13a70 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
13a80 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
13a90 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
13aa0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13ab0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13ac0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13ad0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13ae0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13af0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13b00 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13b10 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
13b20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13b30 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
13b40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
13b50 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
13b60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
13b70 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13b80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
13b90 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
13ba0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13bb0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13bc0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
13bd0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
13be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13bf0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
13c00 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13c10 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
13c20 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13c30 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13c40 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13c50 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13c60 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13c70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13c80 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
13c90 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13ca0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13cb0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
13cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13cd0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
13ce0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
13cf0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
13d00 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
13d10 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
13d20 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
13d30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13d40 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
13d50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13d60 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
13d70 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
13d80 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
13d90 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
13da0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
13db0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
13dc0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
13dd0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
13de0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
13df0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
13e00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13e10 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
13e20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
13e30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13e40 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13e50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13e60 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13e70 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13e80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13e90 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13ea0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
13eb0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
13ec0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13ed0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
13ee0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
13ef0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13f00 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
13f10 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
13f20 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13f30 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
13f40 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13f50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13f60 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
13f70 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13f80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13f90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
13fa0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
13fb0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
13fc0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13fd0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13fe0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13ff0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
14000 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
14010 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
14020 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
14030 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
14040 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
14050 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
14060 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14080 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14090 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
140a0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
140b0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
140c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
140d0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
140e0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
140f0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
14100 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
14110 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
14120 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
14130 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
14140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14150 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
14160 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
14170 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
14180 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
14190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
141a0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
141b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
141c0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
141d0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
141e0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
141f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14200 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14210 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14220 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14230 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14240 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14250 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
14260 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
14270 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
14280 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
14290 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
142a0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
142b0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
142c0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
142d0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
142e0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
142f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14300 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
14310 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14320 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
14330 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14340 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14350 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14360 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
14370 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14380 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14390 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
143a0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
143b0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
143c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
143d0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
143e0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
143f0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
14400 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
14410 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14420 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
14430 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
14440 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14450 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14460 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
14470 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
14480 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
14490 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
144a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
144b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
144c0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
144d0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
144e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
144f0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
14500 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14510 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14520 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
14530 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14540 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
14550 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14560 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
14570 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14580 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14590 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
145a0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
145b0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
145c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
145d0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
145e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
145f0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14600 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14610 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14620 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
14630 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
14640 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
14650 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
14660 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14670 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
14680 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
14690 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
146a0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
146b0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
146c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
146d0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
146e0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
146f0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
14700 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14710 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
14720 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
14730 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
14740 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14750 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14760 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
14770 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
14780 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14790 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e  .** type int, in
147a0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
147b0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66  oolean, which if
147c0 20 74 72 75 65 20 70 72 6f 76 69 64 65 73 20 61   true provides a
147d0 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69   hint to.** SQLi
147e0 74 65 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c  te that it shoul
147f0 64 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65  d avoid large me
14800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14810 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   if possible..**
14820 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e   SQLite will run
14830 20 66 61 73 74 65 72 20 69 66 20 69 74 20 69 73   faster if it is
14840 20 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61   free to make la
14850 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14860 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73  ations,.** but s
14870 6f 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ome application 
14880 6d 69 67 68 74 20 70 72 65 66 65 72 20 74 6f 20  might prefer to 
14890 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78  run slower in ex
148a0 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75  change for.** gu
148b0 61 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d  arantees about m
148c0 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74  emory fragmentat
148d0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73  ion that are pos
148e0 73 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a  sible if large.*
148f0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72  * allocations ar
14900 65 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73  e avoided.  This
14910 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c   hint is normall
14920 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  y off..** </dd>.
14930 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14940 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14950 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14960 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
14970 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14990 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
149a0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
149b0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
149c0 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
149d0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
149e0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
149f0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
14a00 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
14a10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14a20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
14a30 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
14a40 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14a50 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
14a60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
14a70 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
14a80 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
14a90 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
14aa0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
14ab0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14ac0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
14ad0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14ae0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
14af0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14b00 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
14b10 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14b20 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
14b30 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
14b40 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
14b50 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14b60 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
14b70 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
14b80 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
14b90 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
14ba0 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
14bb0 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
14bc0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
14bd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14be0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
14bf0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14c00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14c20 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
14c30 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
14c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c60 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69  SCRATCH option i
14c70 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  s no longer used
14c80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14ca0 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
14cb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14cc0 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
14cd0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14ce0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14cf0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
14d00 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
14d10 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
14d20 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
14d30 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
14d40 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
14d50 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
14d60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14d70 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
14d80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14d90 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
14da0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
14db0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
14dc0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14dd0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
14de0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
14df0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
14e00 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
14e10 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14e20 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14e30 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
14e40 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
14e50 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
14e60 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
14e70 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
14e80 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
14e90 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
14ea0 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
14eb0 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
14ec0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
14ed0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
14ee0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
14ef0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
14f00 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
14f10 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
14f20 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
14f30 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
14f40 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
14f50 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
14f60 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
14f70 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
14f80 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
14f90 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
14fa0 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
14fb0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
14fc0 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
14fd0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
14fe0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
14ff0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
15000 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
15010 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
15020 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
15030 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
15040 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
15050 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
15060 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15070 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
15080 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
15090 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
150a0 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
150b0 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
150c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
150d0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
150e0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
150f0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
15100 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
15110 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
15120 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
15130 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
15140 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
15150 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15160 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
15170 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
15180 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
15190 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
151a0 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
151b0 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
151c0 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
151d0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
151e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
151f0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
15200 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
15210 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
15220 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
15230 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
15240 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
15250 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
15260 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
15270 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
15280 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
15290 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
152a0 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
152b0 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
152c0 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
152d0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
152e0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
152f0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
15300 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
15310 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
15320 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
15330 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
15340 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
15350 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
15360 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
15370 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15380 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
15390 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
153a0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
153b0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
153c0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
153d0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
153e0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
153f0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
15400 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
15410 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
15420 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
15430 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
15440 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
15450 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
15460 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15470 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
15480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15490 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
154a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
154b0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
154c0 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
154d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
154e0 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
154f0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
15500 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
15510 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
15520 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
15530 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
15540 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
15550 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15560 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
15570 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
15580 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
15590 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
155a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
155b0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
155c0 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
155d0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
155e0 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
155f0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
15600 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
15610 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
15620 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
15630 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
15640 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
15650 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
15660 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
15670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
15680 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
15690 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
156a0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
156b0 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
156c0 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
156d0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
156e0 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
156f0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
15700 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
15710 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
15720 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
15730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15740 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
15750 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
15760 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
15770 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
15780 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
15790 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
157a0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
157b0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
157c0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
157d0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
157e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
157f0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
15800 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
15810 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
15820 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15830 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
15840 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
15850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
15870 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15880 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
15890 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
158b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
158c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
158d0 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
158e0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
158f0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15900 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15910 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
15920 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
15930 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
15940 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
15950 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
15960 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
15970 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
15980 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
15990 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
159a0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
159b0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
159c0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
159d0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
159e0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
159f0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
15a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15a10 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
15a20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15a30 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15a40 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15a50 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15a60 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15a70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a80 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
15a90 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
15aa0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15ab0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15ac0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15ad0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15ae0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b00 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
15b10 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
15b20 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
15b30 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
15b40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15b50 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
15b60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15b70 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
15b80 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15ba0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15bb0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15bc0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
15bd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15be0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15bf0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15c00 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15c10 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
15c20 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15c30 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
15c40 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
15c50 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
15c60 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
15c70 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
15c80 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
15c90 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
15ca0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
15cb0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
15cc0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
15cd0 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
15ce0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
15cf0 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
15d00 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
15d10 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
15d20 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
15d30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15d40 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15d50 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15d60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15d70 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15d80 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15d90 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
15da0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
15db0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
15dc0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
15dd0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
15de0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
15df0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
15e00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15e10 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
15e20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
15e30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
15e40 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
15e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15e60 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
15e70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
15e80 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15e90 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15ea0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15eb0 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
15ec0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
15ed0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
15ee0 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
15ef0 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
15f00 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
15f10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f20 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
15f30 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
15f40 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15f50 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15f60 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
15f70 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
15f80 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
15f90 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
15fa0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
15fb0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
15fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15fd0 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
15fe0 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
15ff0 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
16000 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
16010 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
16020 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
16030 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16040 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
16050 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16060 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
16070 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
16080 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
16090 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
160a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
160b0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
160c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
160d0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
160e0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
160f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
16100 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16110 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
16120 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
16130 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
16140 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16150 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
16160 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
16170 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
16180 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
16190 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
161a0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
161b0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
161c0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
161d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
161e0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
161f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16200 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16210 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
16220 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16230 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
16240 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16250 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
16260 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16270 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16280 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
16290 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
162a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
162b0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
162c0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
162d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
162e0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
162f0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
16300 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
16310 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16320 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
16330 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
16340 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
16350 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16360 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
16370 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
16380 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
16390 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
163a0 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
163b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
163c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
163d0 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
163e0 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
163f0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
16400 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
16410 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
16420 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
16430 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
16440 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
16450 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
16460 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
16470 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
16480 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
16490 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
164a0 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
164b0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
164c0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
164d0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
164e0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
164f0 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
16500 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
16510 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
16520 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
16530 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
16540 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
16550 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
16560 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
16570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16580 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16590 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
165a0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
165b0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
165c0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
165d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
165e0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
165f0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
16600 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
16610 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
16630 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
16640 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
16650 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
16660 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
16670 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
16680 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
16690 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
166a0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
166b0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
166c0 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
166d0 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
166e0 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
166f0 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
16700 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
16710 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
16720 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
16730 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
16740 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
16750 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
16760 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
16770 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
16780 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
16790 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
167a0 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
167b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
167c0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
167d0 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
167e0 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
167f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16800 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
16810 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
16820 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
16830 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
16840 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16850 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
16860 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
16870 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
16880 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16890 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
168a0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
168b0 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
168c0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
168d0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
168e0 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
168f0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16900 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
16910 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
16920 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
16930 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
16940 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
16950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
16960 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
16970 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
16980 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
16990 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
169a0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
169b0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
169c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
169d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
169e0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
169f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
16a00 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16a10 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
16a20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
16a30 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
16a40 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
16a50 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
16a60 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
16a70 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
16a80 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
16a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16aa0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
16ab0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
16ac0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16ad0 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
16ae0 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
16af0 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
16b00 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
16b10 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16b20 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
16b30 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
16b40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16b50 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16b60 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
16b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16b80 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16b90 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16bb0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
16bc0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16bd0 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
16be0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
16bf0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
16c00 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
16c10 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
16c20 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
16c30 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
16c40 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
16c50 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
16c60 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
16c70 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
16c80 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
16c90 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
16ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
16cb0 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
16cc0 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
16cd0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
16ce0 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
16cf0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
16d00 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
16d10 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
16d20 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
16d30 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
16d40 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
16d50 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
16d60 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
16d70 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
16d80 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
16d90 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
16da0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
16db0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
16dc0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
16dd0 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
16de0 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
16df0 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
16e00 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
16e10 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
16e20 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
16e30 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
16e40 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
16e50 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
16e60 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
16e70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16e80 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
16e90 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16ea0 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
16eb0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16ec0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
16ed0 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
16ee0 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
16ef0 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
16f00 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
16f10 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
16f20 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
16f30 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
16f40 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
16f50 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
16f60 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
16f70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16f80 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
16f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16fa0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
16fb0 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
16fc0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
16fd0 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
16fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
16ff0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
17000 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
17010 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17020 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
17030 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
17040 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
17050 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
17060 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
17070 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
17080 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
17090 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
170a0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
170b0 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
170c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
170d0 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
170e0 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
170f0 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
17100 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
17110 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
17120 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
17130 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17140 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
17150 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
17160 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
17170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17180 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
17190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
171a0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
171b0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
171c0 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
171d0 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
171e0 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
171f0 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
17200 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
17210 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
17220 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
17230 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
17240 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
17250 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
17260 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
17270 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
17280 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
17290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
172a0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
172b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
172c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
172d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
172e0 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
172f0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
17300 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
17310 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
17320 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
17330 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
17340 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17350 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
17360 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
17370 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
17380 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
17390 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
173a0 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
173b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
173c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
173d0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
173e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
173f0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
17400 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17410 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
17420 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
17430 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
17440 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
17450 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
17460 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
17470 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17480 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
17490 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
174a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
174b0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
174c0 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
174d0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
174e0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
174f0 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
17500 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
17510 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
17520 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17530 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
17540 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
17550 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
17560 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
17570 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
17580 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
17590 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
175a0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
175b0 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
175c0 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
175d0 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
175e0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
175f0 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
17600 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
17610 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
17620 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
17630 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
17640 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
17650 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
17660 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
17670 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
17680 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
17690 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
176a0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
176b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
176c0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
176d0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
176e0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
176f0 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
17700 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17710 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17720 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
17730 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
17740 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
17750 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
17760 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
17770 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
17780 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
17790 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
177a0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
177b0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
177c0 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
177d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
177e0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
177f0 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
17800 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
17810 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
17820 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17830 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
17840 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17850 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17860 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17880 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
17890 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
178a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
178b0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
178c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
178d0 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
178e0 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
178f0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
17900 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
17910 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
17920 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
17930 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
17940 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
17950 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
17960 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
17970 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
17980 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
17990 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
179a0 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
179b0 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
179c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
179d0 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
179e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
179f0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17a10 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17a20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17a30 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17a40 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
17a50 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
17a60 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
17a70 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
17a80 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
17a90 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
17aa0 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
17ab0 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
17ac0 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
17ad0 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
17ae0 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
17af0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
17b00 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
17b10 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
17b20 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
17b30 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
17b40 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
17b50 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
17b60 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
17b70 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
17b80 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
17b90 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
17ba0 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
17bb0 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
17bc0 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
17bd0 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
17be0 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
17bf0 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
17c00 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
17c10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17c20 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17c30 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
17c40 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17c50 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
17c60 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17c70 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17c80 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
17c90 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
17ca0 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
17cb0 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
17cc0 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
17cd0 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
17ce0 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
17cf0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
17d00 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
17d10 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
17d20 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
17d30 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
17d40 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
17d50 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
17d60 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
17d70 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
17d80 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
17d90 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17da0 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
17db0 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
17dc0 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
17dd0 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
17de0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
17df0 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
17e00 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
17e10 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
17e20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
17e30 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
17e40 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
17e50 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
17e60 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
17e70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
17e80 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
17e90 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
17ea0 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
17eb0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
17ec0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
17ed0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
17ee0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17ef0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17f00 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
17f10 52 45 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  REF_SIZE]].** <d
17f20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17f30 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 0a 2a  SORTERREF_SIZE.*
17f40 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
17f50 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
17f60 46 5f 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63  F_SIZE option ac
17f70 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70  cepts a single p
17f80 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20 74  arameter.** of t
17f90 79 70 65 20 28 69 6e 74 29 20 2d 20 74 68 65 20  ype (int) - the 
17fa0 6e 65 77 20 76 61 6c 75 65 20 6f 66 20 74 68 65  new value of the
17fb0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
17fc0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
17fd0 2e 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77 68  ..** Usually, wh
17fe0 65 6e 20 53 51 4c 69 74 65 20 75 73 65 73 20 61  en SQLite uses a
17ff0 6e 20 65 78 74 65 72 6e 61 6c 20 73 6f 72 74 20  n external sort 
18000 74 6f 20 6f 72 64 65 72 20 72 65 63 6f 72 64 73  to order records
18010 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
18020 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61   an ORDER BY cla
18030 75 73 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73 20  use, all fields 
18040 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20  required by the 
18050 63 61 6c 6c 65 72 20 61 72 65 20 70 72 65 73 65  caller are prese
18060 6e 74 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f 72  nt in the.** sor
18070 74 65 64 20 72 65 63 6f 72 64 73 2e 20 48 6f 77  ted records. How
18080 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
18090 64 65 74 65 72 6d 69 6e 65 73 20 62 61 73 65 64  determines based
180a0 20 6f 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64   on the declared
180b0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74 61   type.** of a ta
180c0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
180d0 69 74 73 20 76 61 6c 75 65 73 20 61 72 65 20 6c  its values are l
180e0 69 6b 65 6c 79 20 74 6f 20 62 65 20 76 65 72 79  ikely to be very
180f0 20 6c 61 72 67 65 20 2d 20 6c 61 72 67 65 72 0a   large - larger.
18100 2a 2a 20 74 68 61 6e 20 74 68 65 20 63 6f 6e 66  ** than the conf
18110 69 67 75 72 65 64 20 73 6f 72 74 65 72 2d 72 65  igured sorter-re
18120 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
18130 65 73 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61 20  eshold - then a 
18140 72 65 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73 20  reference.** is 
18150 73 74 6f 72 65 64 20 69 6e 20 65 61 63 68 20 73  stored in each s
18160 6f 72 74 65 64 20 72 65 63 6f 72 64 20 61 6e 64  orted record and
18170 20 74 68 65 20 72 65 71 75 69 72 65 64 20 63 6f   the required co
18180 6c 75 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61 64  lumn values load
18190 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 64  ed.** from the d
181a0 61 74 61 62 61 73 65 20 61 73 20 72 65 63 6f 72  atabase as recor
181b0 64 73 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  ds are returned 
181c0 69 6e 20 73 6f 72 74 65 64 20 6f 72 64 65 72 2e  in sorted order.
181d0 20 54 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   The default.** 
181e0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f  value for this o
181f0 70 74 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76 65  ption is to neve
18200 72 20 75 73 65 20 74 68 69 73 20 6f 70 74 69 6d  r use this optim
18210 69 7a 61 74 69 6f 6e 2e 20 53 70 65 63 69 66 79  ization. Specify
18220 69 6e 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74 69  ing a .** negati
18230 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  ve value for thi
18240 73 20 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72 65  s option restore
18250 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  s the default be
18260 68 61 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69 73  haviour..** This
18270 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
18280 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
18290 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
182a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
182b0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 45  ITE_ENABLE_SORTE
182c0 52 5f 52 45 46 45 52 45 4e 43 45 53 5d 20 63 6f  R_REFERENCES] co
182d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
182e0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
182f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18300 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
18310 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
18320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18330 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
18340 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
18350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18360 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
18370 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
18380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18390 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
183a0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
183b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
183c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
183d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
183e0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
183f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
18400 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
18410 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
18420 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
18430 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
18440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18450 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
18460 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
18470 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
18480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18490 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
184a0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
184b0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
184c0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
184d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
184e0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
184f0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
18500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18510 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
18520 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
18530 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
18540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18550 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
18560 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
18570 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18580 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
18590 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
185a0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
185b0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
185c0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
185d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
185f0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
18600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18610 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
18620 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
18630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18640 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
18650 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
18660 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
18680 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
18690 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
186a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
186b0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
186c0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
186d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
186e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
186f0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
18700 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18710 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18730 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
18740 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18750 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18760 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18770 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
18780 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
18790 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
187a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
187b0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
187c0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
187d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187e0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
187f0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
18800 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
18810 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
18820 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18830 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
18840 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
18850 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
18860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18870 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
18880 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
18890 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
188a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
188b0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
188c0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
188d0 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
188e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
188f0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18900 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
18910 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
18920 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18930 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20  _SMALL_MALLOC   
18940 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c       27  /* bool
18950 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52  QLITE_CONFIG_SOR
18970 54 45 52 52 45 46 5f 53 49 5a 45 20 20 20 20 20  TERREF_SIZE     
18980 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   28  /* int nByt
18990 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
189a0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
189b0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
189c0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
189d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
189e0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
189f0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
18a00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18a10 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
18a20 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
18a30 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18a40 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
18a50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18a60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
18a70 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
18a80 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
18a90 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
18aa0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
18ab0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
18ac0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
18ad0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
18ae0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
18af0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
18b00 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
18b10 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
18b20 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
18b30 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
18b40 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
18b50 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
18b60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
18b70 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
18b80 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
18b90 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
18ba0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
18bb0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
18bc0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
18bd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18be0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
18bf0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18c00 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18c10 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
18c20 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18c30 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
18c40 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
18c50 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
18c60 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
18c70 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18c80 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
18c90 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
18ca0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18cb0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
18cc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
18cd0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
18ce0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
18cf0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
18d00 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
18d10 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
18d20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
18d30 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
18d40 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
18d50 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
18d60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18d70 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
18d80 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
18d90 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
18da0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
18db0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
18dc0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
18dd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
18de0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
18df0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
18e00 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
18e10 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
18e20 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
18e30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
18e40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
18e50 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
18e60 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
18e70 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
18e80 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
18e90 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
18ea0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
18eb0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
18ec0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
18ed0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
18ee0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
18ef0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
18f00 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
18f10 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
18f20 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
18f30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18f40 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
18f50 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
18f60 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
18f70 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
18f80 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
18f90 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
18fa0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
18fb0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
18fc0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
18fd0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
18fe0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
18ff0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
19000 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
19010 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
19020 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
19030 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
19040 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
19050 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
19060 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
19070 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
19080 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
19090 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
190a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
190b0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
190c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
190d0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
190e0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
190f0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
19100 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
19110 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
19120 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
19130 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
19140 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
19150 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
19160 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19170 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19180 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
19190 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
191a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
191b0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
191c0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
191d0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
191e0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
191f0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19200 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19210 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19220 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19230 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19240 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19250 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
19260 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
19270 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
19280 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
19290 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
192a0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
192b0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
192c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
192d0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
192e0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
192f0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19300 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19310 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19320 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19330 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
19340 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19350 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19360 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19370 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19380 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19390 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
193a0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
193b0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
193c0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
193d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
193e0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
193f0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
19400 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19410 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19420 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
19430 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
19440 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
19450 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19460 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19470 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19480 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19490 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
194a0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
194b0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
194c0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
194d0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
194e0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
194f0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19500 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19520 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19530 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19540 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19550 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19560 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
19570 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
19580 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19590 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
195a0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
195b0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
195c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
195d0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
195e0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
195f0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19600 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19610 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19620 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19630 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19640 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19650 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19660 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19670 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
19680 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
19690 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
196a0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
196b0 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
196c0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
196d0 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
196e0 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
196f0 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
19700 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19710 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19720 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19730 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19740 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19750 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19760 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19770 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
19780 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
19790 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
197a0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
197b0 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
197c0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
197d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
197e0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
197f0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19800 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19810 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19820 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19830 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
19840 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
19850 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
19860 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19870 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19880 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
19890 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
198a0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
198b0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
198c0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
198d0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
198e0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
198f0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
19900 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
19910 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19920 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19930 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
19950 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
19960 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
19970 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
19980 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
19990 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
199a0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
199b0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
199c0 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
199d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
199e0 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
199f0 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
19a00 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
19a10 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
19a20 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
19a30 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
19a40 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19a50 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19a60 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
19a70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19a80 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
19a90 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
19aa0 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
19ab0 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
19ac0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19ad0 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
19ae0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
19af0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19b00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19b10 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
19b20 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
19b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
19b40 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
19b50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19b60 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
19b70 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
19b80 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
19b90 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
19ba0 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
19bb0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
19bc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19bd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19be0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
19bf0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
19c00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
19c10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
19c20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
19c30 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
19c40 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
19c50 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
19c60 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19c70 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19c80 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
19c90 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19ca0 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
19cb0 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
19cc0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19cd0 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
19ce0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19cf0 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
19d00 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
19d10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19d20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
19d30 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
19d40 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
19d50 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
19d60 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
19d70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19d80 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
19d90 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
19da0 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
19db0 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
19dc0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
19dd0 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
19de0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
19df0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
19e00 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
19e10 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
19e20 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
19e30 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
19e40 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
19e50 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
19e60 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
19e70 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
19e80 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
19e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19ea0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
19eb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19ec0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
19ed0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f  _CKPT_ON_CLOSE</
19ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61  dt>.** <dd> Usua
19ef0 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61  lly, when a data
19f00 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65  base in wal mode
19f10 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65   is closed or de
19f20 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a  tached from a .*
19f30 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
19f40 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73  e, SQLite checks
19f50 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65   if this will me
19f60 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72  an that there ar
19f70 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e  e now no .** con
19f80 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20  nections at all 
19f90 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
19fa0 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f   If so, it perfo
19fb0 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rms a checkpoint
19fc0 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62   .** operation b
19fd0 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68  efore closing th
19fe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
19ff0 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65  is option may be
1a000 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72   used to.** over
1a010 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69  ride this behavi
1a020 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  our. The first p
1a030 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
1a040 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
1a050 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  n.** is an integ
1a060 65 72 20 2d 20 70 6f 73 69 74 69 76 65 20 74 6f  er - positive to
1a070 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f   disable checkpo
1a080 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f  ints-on-close, o
1a090 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64  r zero (the.** d
1a0a0 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c  efault) to enabl
1a0b0 65 20 74 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61  e them, and nega
1a0c0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1a0d0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1a0e0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1a0f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a100 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1a110 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20  integer.** into 
1a120 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
1a130 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1a140 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63  ate whether chec
1a150 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
1a160 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69  .** have been di
1a170 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68  sabled - 0 if th
1a180 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62  ey are not disab
1a190 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61  led, 1 if they a
1a1a0 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  re..** </dd>.**.
1a1b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a1c0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
1a1d0 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SG</dt>.** <dd>^
1a1e0 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  (The SQLITE_DBCO
1a1f0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
1a200 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
1a210 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
1a220 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70  .** the [query p
1a230 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79  lanner stability
1a240 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53   guarantee] (QPS
1a250 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50  G).  When the QP
1a260 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a  SG is active,.**
1a270 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75   a single SQL qu
1a280 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ery statement wi
1a290 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
1a2a0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
1a2b0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
1a2c0 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75  f values of [bou
1a2d0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  nd parameters].)
1a2e0 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62  ^ The QPSG disab
1a2f0 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f  les some query o
1a300 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20  ptimizations.** 
1a310 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65  that look at the
1a320 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64   values of bound
1a330 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69   parameters, whi
1a340 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65  ch can make some
1a350 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77   queries.** slow
1a360 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53  er.  But the QPS
1a370 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74  G has the advant
1a380 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64  age of more pred
1a390 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  ictable behavior
1a3a0 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51  .  With.** the Q
1a3b0 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69  PSG active, SQLi
1a3c0 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  te will always u
1a3d0 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72  se the same quer
1a3e0 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69  y plan in the fi
1a3f0 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73  eld as.** was us
1a400 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
1a410 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a  g in the lab..**
1a420 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1a430 65 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74  ent to this sett
1a440 69 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ing is an intege
1a450 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
1a460 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20  disable .** the 
1a470 51 50 53 47 2c 20 70 6f 73 69 74 69 76 65 20 74  QPSG, positive t
1a480 6f 20 65 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f  o enable QPSG, o
1a490 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
1a4a0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
1a4b0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68  ** unchanged. Th
1a4c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a4d0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a4e0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a4f0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a500 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a510 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a520 72 20 74 68 65 20 51 50 53 47 20 69 73 20 64 69  r the QPSG is di
1a530 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a540 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
1a550 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64  his call..** </d
1a560 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49  ITE_DBCONFIG_TRI
1a580 47 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a  GGER_EQP</dt>.**
1a590 20 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c 74   <dd> By default
1a5a0 2c 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  , the output of 
1a5b0 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c  EXPLAIN QUERY PL
1a5c0 41 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73  AN commands does
1a5d0 20 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65   not .** include
1a5e0 20 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79 20   output for any 
1a5f0 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f  operations perfo
1a600 72 6d 65 64 20 62 79 20 74 72 69 67 67 65 72 20  rmed by trigger 
1a610 70 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a  programs. This.*
1a620 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1a630 20 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72   to set or clear
1a640 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 20 61   (the default) a
1a650 20 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65 72   flag that gover
1a660 6e 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61 76  ns this.** behav
1a670 69 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  ior. The first p
1a680 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
1a690 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
1a6a0 6e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  n is an integer 
1a6b0 2d 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  -.** positive to
1a6c0 20 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20 66   enable output f
1a6d0 6f 72 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  or trigger progr
1a6e0 61 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20  ams, or zero to 
1a6f0 64 69 73 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f  disable it,.** o
1a700 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
1a710 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
1a720 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
1a730 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a740 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a750 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a760 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74  to which is writ
1a770 74 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74  ten .** 0 or 1 t
1a780 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a790 65 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72  er output-for-tr
1a7a0 69 67 67 65 72 73 20 68 61 73 20 62 65 65 6e 20  iggers has been 
1a7b0 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20  disabled - 0 if 
1a7c0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64 69  .** it is not di
1a7d0 73 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74 20  sabled, 1 if it 
1a7e0 69 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  is.  .** </dd>.*
1a7f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a800 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1a810 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20  ATABASE</dt>.** 
1a820 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c  <dd> Set the SQL
1a830 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1a840 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67  ET_DATABASE flag
1a850 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a   and then run.**
1a860 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64   [VACUUM] in ord
1a870 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64 61  er to reset a da
1a880 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61  tabase back to a
1a890 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73 65  n empty database
1a8a0 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65  .** with no sche
1a8b0 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e  ma and no conten
1a8c0 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  t. The following
1a8d0 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65   process works e
1a8e0 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64  ven for.** a bad
1a8f0 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61 74  ly corrupted dat
1a900 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c  abase file:.** <
1a910 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74  ol>.** <li> If t
1a920 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a930 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20  ection is newly 
1a940 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72  opened, make sur
1a950 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74 68  e it has read th
1a960 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61  e.**      databa
1a970 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72 65  se schema by pre
1a980 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63  paring then disc
1a990 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72  arding some quer
1a9a0 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a  y against the.**
1a9b0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c 20        database, 
1a9c0 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  or calling sqlit
1a9d0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1a9e0 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f  metadata(), igno
1a9f0 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20  ring any.**     
1aa00 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73   errors.  This s
1aa10 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65  tep is only nece
1aa20 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70 70  ssary if the app
1aa30 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73  lication desires
1aa40 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20   to keep.**     
1aa50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1aa60 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20   WAL mode after 
1aa70 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74 20  the reset if it 
1aa80 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20  was in WAL mode 
1aa90 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74  before.**      t
1aaa0 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c  he reset.  .** <
1aab0 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1aac0 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1aad0 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1aae0 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b  DATABASE, 1, 0);
1aaf0 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  .** <li> [sqlite
1ab00 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41  3_exec](db, "[VA
1ab10 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29  CUUM]", 0, 0, 0)
1ab20 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ;.** <li> sqlite
1ab30 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1ab40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ab50 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1ab60 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  0, 0);.** </ol>.
1ab70 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74  ** Because reset
1ab80 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ting a database 
1ab90 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61  is destructive a
1aba0 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c  nd irreversible,
1abb0 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20   the.** process 
1abc0 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65  requires the use
1abd0 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65   of this obscure
1abe0 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c   API and multipl
1abf0 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a  e steps to help.
1ac00 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69  ** ensure that i
1ac10 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65  t does not happe
1ac20 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a  n by accident..*
1ac30 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  * </dd>.** </dl>
1ac40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1ac50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1ac60 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
1ac70 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
1ac80 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
1ac90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1aca0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
1acb0 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
1acc0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
1acd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ace0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
1acf0 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
1ad00 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
1ad10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ad20 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1ad30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ad40 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
1ad50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ad60 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1ad70 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
1ad80 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
1ad90 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1ada0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1adb0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
1adc0 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
1add0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1ade0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1adf0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
1ae00 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
1ae10 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1ae20 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1ae30 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
1ae40 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
1ae50 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1ae60 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1ae70 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20  FIG_TRIGGER_EQP 
1ae80 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
1ae90 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1aea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1aeb0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1aec0 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30 39  BASE        1009
1aed0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1aee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1aef0 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20  BCONFIG_MAX     
1af00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1af10 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42  09 /* Largest DB
1af20 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  CONFIG */../*.**
1af30 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1af40 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1af50 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1af60 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1af70 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1af80 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1af90 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1afa0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1afb0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1afc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1afd0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1afe0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1aff0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1b000 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1b010 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1b020 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1b030 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1b040 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1b050 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
1b060 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
1b070 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1b080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1b090 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1b0a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b0b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
1b0c0 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
1b0d0 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
1b0e0 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
1b0f0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
1b100 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
1b110 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
1b120 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
1b130 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
1b140 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
1b150 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
1b160 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
1b170 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
1b180 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
1b190 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
1b1a0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
1b1b0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
1b1c0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
1b1d0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1b1e0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
1b1f0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
1b200 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
1b210 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
1b220 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
1b230 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
1b240 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
1b250 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
1b260 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b270 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b280 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
1b290 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
1b2a0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
1b2b0 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
1b2c0 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
1b2d0 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
1b2e0 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
1b2f0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
1b300 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
1b310 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
1b320 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
1b330 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
1b340 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
1b350 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
1b360 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
1b370 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1b380 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1b390 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
1b3a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b3b0 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
1b3c0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b3d0 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1b3e0 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
1b3f0 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
1b400 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
1b410 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
1b420 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
1b430 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
1b440 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b450 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1b460 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
1b470 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
1b480 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1b490 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b4a0 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
1b4b0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1b4c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1b4d0 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
1b4e0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
1b4f0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
1b500 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
1b510 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
1b520 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
1b530 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
1b540 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
1b550 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
1b560 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
1b570 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b580 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
1b590 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b5a0 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
1b5b0 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
1b5c0 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
1b5d0 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
1b5e0 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
1b5f0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1b600 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
1b610 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
1b620 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
1b630 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
1b640 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
1b650 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
1b660 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
1b670 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
1b680 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1b690 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
1b6a0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
1b6b0 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
1b6c0 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
1b6d0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1b6e0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1b6f0 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
1b700 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
1b710 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1b720 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1b730 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
1b740 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
1b750 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
1b760 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1b770 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
1b780 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b790 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1b7a0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1b7b0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1b7c0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
1b7d0 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
1b7e0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
1b7f0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
1b800 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1b810 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
1b820 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
1b830 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
1b840 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1b850 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b860 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
1b870 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
1b880 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
1b890 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
1b8a0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
1b8b0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
1b8c0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
1b8d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
1b8e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1b8f0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
1b900 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
1b910 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
1b920 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
1b930 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
1b940 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
1b950 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
1b960 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
1b970 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
1b980 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
1b990 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
1b9a0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
1b9b0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
1b9c0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
1b9d0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1b9e0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
1b9f0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
1ba00 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1ba10 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
1ba20 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
1ba30 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
1ba40 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
1ba50 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
1ba60 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
1ba70 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
1ba80 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
1ba90 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
1baa0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1bab0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
1bac0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
1bad0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
1bae0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1baf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1bb00 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1bb10 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
1bb20 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
1bb30 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
1bb40 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1bb50 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
1bb60 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1bb70 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1bb80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1bb90 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
1bba0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
1bbb0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
1bbc0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
1bbd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1bbe0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1bbf0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
1bc00 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1bc10 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
1bc20 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
1bc30 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
1bc40 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1bc50 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
1bc60 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1bc70 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bc80 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1bc90 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1bca0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1bcb0 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1bcc0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1bcd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bce0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1bcf0 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1bd00 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1bd10 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1bd20 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1bd30 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1bd40 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1bd50 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1bd60 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1bd70 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1bd80 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1bd90 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
1bda0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1bdb0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1bdc0 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
1bdd0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1bde0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1bdf0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1be00 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1be10 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1be20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1be30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1be40 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1be50 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1be60 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1be70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1be80 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1be90 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1bea0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1beb0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1bec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1bed0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1bee0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1bef0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1bf00 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1bf10 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1bf20 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1bf30 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1bf40 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1bf50 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1bf60 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1bf70 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1bf80 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1bf90 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1bfa0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1bfb0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1bfc0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1bfd0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1bfe0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1bff0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1c000 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1c010 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1c020 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1c030 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1c040 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1c050 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1c060 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1c070 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1c080 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1c090 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1c0a0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1c0b0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1c0c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1c0d0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1c0e0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1c0f0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1c100 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1c110 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1c120 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1c130 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1c140 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1c150 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1c160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1c170 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1c180 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1c190 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1c1a0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1c1b0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1c1c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1c1d0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1c1e0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1c1f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1c200 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1c210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1c220 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1c230 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1c240 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1c250 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1c260 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1c270 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1c280 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1c290 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1c2a0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1c2b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c2c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1c2d0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c2e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1c2f0 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1c300 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1c310 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1c320 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1c330 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1c340 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1c350 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1c360 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1c370 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1c380 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1c390 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1c3a0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1c3b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c3c0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1c3d0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1c3e0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1c3f0 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1c400 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1c410 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1c420 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1c430 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1c440 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1c450 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1c460 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1c470 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1c480 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1c490 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1c4a0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1c4b0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1c4c0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1c4d0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1c4e0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1c4f0 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1c500 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1c510 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1c520 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c530 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1c540 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1c550 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1c560 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1c570 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1c580 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1c590 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1c5a0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1c5b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1c5c0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1c5d0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1c5e0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1c5f0 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1c600 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1c610 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1c620 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1c630 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1c640 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1c650 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1c660 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1c670 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1c680 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1c690 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1c6a0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1c6b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1c6c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1c6d0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1c6e0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1c6f0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1c700 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1c710 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1c720 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1c730 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
1c740 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  o:.** <ul>.** <l
1c750 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  i> the [sqlite3_
1c760 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1c770 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c   interface.** <l
1c780 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68  i> the [count_ch
1c790 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a  anges pragma].**
1c7a0 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67   <li> the [chang
1c7b0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1c7c0 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  n].** <li> the [
1c7d0 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61  data_version pra
1c7e0 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  gma].** </ul>.*/
1c7f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
1c800 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1c810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c820 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1c830 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1c840 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c850 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1c860 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1c870 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1c880 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1c890 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1c8a0 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1c8b0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1c8c0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1c8d0 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1c8e0 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1c8f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c900 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1c910 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1c920 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1c930 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1c940 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1c950 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1c960 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1c970 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1c980 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1c990 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1c9a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1c9b0 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1c9c0 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1c9d0 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1c9e0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1c9f0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1ca00 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1ca10 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1ca20 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1ca30 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1ca40 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1ca50 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1ca60 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1ca70 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1ca80 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1ca90 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1caa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 74 68  d..**.** This th
1cab0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1cac0 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74  _changes(D)] int
1cad0 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1cae0 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rts the number.*
1caf0 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63  * of rows that c
1cb00 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51  hanged due to SQ
1cb10 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  L statement run 
1cb20 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65  against database
1cb30 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
1cb40 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62  .  Any changes b
1cb50 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  y other database
1cb60 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65   connections are
1cb70 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20   ignored..** To 
1cb80 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61  detect changes a
1cb90 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73  gainst a databas
1cba0 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65  e file from othe
1cbb0 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
1cbc0 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68  nnections use th
1cbd0 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76  e [PRAGMA data_v
1cbe0 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20  ersion] command 
1cbf0 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  or the.** [SQLIT
1cc00 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52  E_FCNTL_DATA_VER
1cc10 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74  SION] [file cont
1cc20 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rol]..** .** If 
1cc30 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1cc40 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1cc50 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1cc60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1cc70 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1cc80 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1cc90 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1cca0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1ccb0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1ccc0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1ccd0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a  t meaningful..**
1cce0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a  .** See also:.**
1ccf0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68   <ul>.** <li> th
1cd00 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1cd10 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  es()] interface.
1cd20 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75  ** <li> the [cou
1cd30 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1cd40 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1cd50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1cd60 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20  nction].** <li> 
1cd70 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f  the [data_versio
1cd80 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  n pragma].** <li
1cd90 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  > the [SQLITE_FC
1cda0 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
1cdb0 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d  ] [file control]
1cdc0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
1cdd0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1cde0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1cdf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ce00 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1ce10 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1ce20 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1ce30 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ce40 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1ce50 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1ce60 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1ce70 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1ce80 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1ce90 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1cea0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1ceb0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1cec0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1ced0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1cee0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1cef0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1cf00 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1cf10 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1cf20 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1cf30 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1cf40 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1cf50 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1cf60 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1cf70 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1cf80 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1cf90 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1cfa0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1cfb0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1cfc0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1cfd0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1cfe0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1cff0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1d000 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1d010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1d020 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1d030 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1d040 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1d050 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1d060 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1d070 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1d080 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1d090 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1d0a0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1d0b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1d0c0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1d0d0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1d0e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1d0f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1d100 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1d110 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1d120 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1d130 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1d140 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1d150 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1d160 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1d170 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1d180 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1d190 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1d1a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1d1b0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1d1c0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1d1d0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1d1e0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1d1f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1d200 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1d210 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1d220 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1d230 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d240 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1d250 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1d260 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1d270 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d280 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1d290 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1d2a0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1d2b0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1d2c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1d2d0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1d2e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d2f0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1d300 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1d310 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1d320 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1d330 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1d340 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1d350 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1d360 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1d370 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1d380 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1d390 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1d3a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1d3b0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1d3c0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1d3d0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1d3e0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1d3f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1d400 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1d410 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1d420 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1d430 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1d440 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1d450 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1d460 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1d470 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1d480 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1d490 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1d4a0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1d4b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d4c0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1d4d0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1d4e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1d4f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d500 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1d510 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1d520 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1d530 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1d540 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1d550 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1d560 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1d570 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1d580 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1d590 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1d5a0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1d5b0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1d5c0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1d5d0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1d5e0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1d5f0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1d600 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1d610 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1d620 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d630 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1d640 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1d650 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1d660 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1d670 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1d680 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1d690 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1d6a0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1d6b0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1d6c0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1d6d0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1d6e0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1d6f0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1d700 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1d710 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1d720 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1d730 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1d740 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1d750 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1d760 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1d770 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1d780 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1d790 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1d7a0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1d7b0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1d7c0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1d7d0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1d7e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1d7f0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1d800 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1d810 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1d820 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1d830 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1d840 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d850 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1d860 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1d870 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1d880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d890 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1d8a0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1d8b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1d8c0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1d8d0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1d8e0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1d8f0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1d900 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1d910 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1d920 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1d930 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1d940 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1d950 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1d960 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1d970 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1d980 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1d990 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1d9a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1d9b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1d9c0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1d9d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1d9e0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1d9f0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1da00 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1da10 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1da20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1da30 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1da40 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1da50 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1da60 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1da70 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1da80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1da90 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1daa0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1dab0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1dac0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1dad0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1dae0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1daf0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1db00 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1db10 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1db20 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1db30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1db40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1db50 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1db60 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1db70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1db80 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1db90 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1dba0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1dbb0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1dbc0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1dbd0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1dbe0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1dbf0 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1dc00 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1dc10 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1dc20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dc30 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1dc40 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1dc50 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1dc60 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1dc70 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1dc80 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1dc90 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1dca0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1dcb0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1dcc0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1dcd0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1dce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dcf0 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1dd00 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1dd10 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1dd20 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1dd30 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1dd40 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1dd50 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1dd60 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1dd70 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1dd80 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1dd90 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1dda0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1ddb0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1ddc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1ddd0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1dde0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1ddf0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1de00 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1de10 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1de20 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1de30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1de40 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1de50 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1de60 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1de70 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1de80 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1de90 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1dea0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1deb0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1dec0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1ded0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1dee0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1def0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1df00 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1df10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1df20 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1df30 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1df40 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1df50 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1df60 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1df70 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1df80 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1df90 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1dfa0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1dfb0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1dfc0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1dfd0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1dfe0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1dff0 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1e000 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1e010 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1e020 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1e030 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1e040 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1e050 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1e060 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1e070 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1e080 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1e090 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1e0a0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1e0b0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1e0c0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1e0d0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1e0e0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1e0f0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1e100 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1e110 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1e120 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1e130 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1e140 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1e150 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1e160 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1e170 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1e180 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1e190 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1e1a0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1e1b0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1e1c0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1e1d0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1e1e0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1e1f0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1e200 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1e210 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1e220 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1e230 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1e240 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1e250 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1e260 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1e270 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1e280 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1e290 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1e2a0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1e2b0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1e2c0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1e2d0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1e2e0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1e2f0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1e300 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1e310 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1e320 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1e330 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1e340 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1e350 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1e360 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1e370 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1e380 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1e390 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1e3a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1e3b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1e3c0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1e3d0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1e3e0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1e3f0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1e400 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1e410 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1e420 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1e430 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1e440 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1e450 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1e460 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1e470 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1e480 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1e490 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1e4a0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1e4b0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1e4c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1e4d0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1e4e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1e4f0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1e500 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1e510 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1e520 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1e530 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1e540 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1e550 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1e560 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1e570 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1e580 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1e590 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1e5a0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1e5b0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1e5c0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1e5d0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1e5e0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1e5f0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1e600 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1e610 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1e620 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1e630 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1e640 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1e650 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1e660 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1e670 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1e680 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1e690 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1e6a0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1e6b0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1e6c0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1e6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e6e0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1e6f0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1e700 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1e710 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1e720 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e730 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1e740 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1e750 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e760 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1e770 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1e780 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e790 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1e7a0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1e7b0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1e7c0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1e7d0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1e7e0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1e7f0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1e800 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1e810 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1e820 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1e830 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1e840 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1e850 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1e860 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1e870 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1e880 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1e890 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1e8a0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1e8b0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1e8c0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1e8d0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1e8e0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1e8f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1e900 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1e910 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1e920 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1e930 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1e940 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1e950 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1e960 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1e970 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1e980 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1e990 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1e9a0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1e9b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e9c0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1e9d0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1e9e0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1e9f0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1ea00 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1ea10 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ea20 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1ea30 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1ea40 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1ea50 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1ea60 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1ea70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1ea80 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1ea90 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1eaa0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1eab0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1eac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ead0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1eae0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1eaf0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1eb00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1eb10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1eb20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1eb30 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1eb40 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1eb50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1eb60 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1eb70 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1eb80 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1eb90 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1eba0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1ebb0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1ebc0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1ebd0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1ebe0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1ebf0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1ec00 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1ec10 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1ec20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1ec30 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1ec40 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1ec50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1ec60 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1ec70 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1ec80 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1ec90 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1eca0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ecb0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ecc0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ecd0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ece0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ecf0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ed00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ed10 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ed20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ed30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ed40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ed50 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ed60 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1ed70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ed80 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1ed90 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1eda0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1edb0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1edc0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1edd0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1ede0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1edf0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1ee00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1ee10 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1ee20 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1ee30 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1ee40 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1ee50 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1ee60 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1ee70 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1ee80 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1ee90 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1eea0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1eeb0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1eec0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1eed0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1eee0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1eef0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ef00 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1ef10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1ef20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1ef30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ef40 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ef50 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ef60 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1ef70 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ef80 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1ef90 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1efa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1efb0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1efc0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1efd0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1efe0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1eff0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1f000 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1f010 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1f020 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f030 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1f040 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1f050 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1f060 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1f070 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1f080 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1f090 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1f0a0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1f0b0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1f0c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f0d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1f0e0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1f0f0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1f100 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1f110 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1f120 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1f130 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1f140 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1f150 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1f160 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1f170 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1f180 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1f190 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1f1a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f1b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1f1c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1f1d0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1f1e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f1f0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1f200 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f210 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1f220 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f230 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1f240 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1f250 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1f260 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1f270 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1f280 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1f290 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f2a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1f2b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f2c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1f2d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f2e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1f2f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1f300 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1f310 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1f320 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1f330 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1f340 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1f350 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1f360 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1f370 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1f380 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1f390 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1f3a0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1f3b0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1f3c0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1f3d0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1f3e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1f3f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1f400 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1f410 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1f420 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1f430 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1f440 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1f450 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1f460 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1f470 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1f480 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1f490 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1f4a0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1f4b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f4c0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1f4d0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1f4e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1f4f0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1f500 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1f510 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1f520 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1f530 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1f540 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1f550 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1f560 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1f570 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1f580 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1f590 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1f5a0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1f5b0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1f5c0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1f5d0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1f5e0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1f5f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1f600 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1f610 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1f620 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1f630 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1f640 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1f650 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1f660 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1f670 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1f680 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1f690 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1f6a0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1f6b0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1f6c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1f6d0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1f6e0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1f6f0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1f700 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1f710 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1f720 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1f730 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1f740 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1f750 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1f760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f770 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1f780 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1f790 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f7a0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1f7b0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1f7c0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1f7d0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1f7e0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1f7f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1f800 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1f810 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1f820 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1f830 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1f840 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1f850 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1f860 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1f870 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1f880 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1f890 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1f8a0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1f8b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1f8c0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1f8d0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1f8e0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1f8f0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1f900 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1f910 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1f920 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1f930 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1f940 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1f950 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1f960 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1f970 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1f980 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1f990 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1f9a0 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74  e common formatt
1f9b0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1f9c0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1f9d0 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66 28   library printf(
1f9e0 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  ) .** plus some 
1f9f0 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1fa00 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 20  tandard formats 
1fa10 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77  ([%q], [%Q], [%w
1fa20 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a  ], and [%z])..**
1fa30 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74 2d   See the [built-
1fa40 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f 63  in printf()] doc
1fa50 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 64  umentation for d
1fa60 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  etails..**.** ^T
1fa70 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1fa80 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1fa90 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1faa0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1fab0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1fac0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1fad0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1fae0 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20 54  alloc64()]..** T
1faf0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1fb00 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1fb10 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1fb20 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1fb30 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1fb40 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1fb50 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1fb60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1fb70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1fb80 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  64()] is unable 
1fb90 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1fba0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1fbb0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1fbc0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1fbd0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1fbe0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1fbf0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1fc00 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1fc10 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1fc20 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1fc30 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1fc40 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1fc50 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1fc60 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1fc70 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1fc80 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1fc90 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1fca0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1fcb0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1fcc0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1fcd0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1fce0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1fcf0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1fd00 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1fd10 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1fd20 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1fd30 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1fd40 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1fd50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1fd60 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1fd70 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1fd80 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1fd90 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1fda0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1fdb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1fdc0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1fdd0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1fde0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1fdf0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1fe00 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1fe10 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1fe20 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1fe30 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1fe40 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1fe50 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1fe60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1fe70 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1fe80 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1fe90 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1fea0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1feb0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1fec0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1fed0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1fee0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1fef0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1ff00 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1ff10 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1ff20 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1ff30 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1ff40 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1ff50 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1ff60 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1ff70 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1ff80 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1ff90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1ffa0 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1ffb0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1ffc0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1ffd0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1ffe0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1fff0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20000 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
20010 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
20020 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
20030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20040 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
20050 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  :  [built-in pri
20060 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66 28  ntf()], [printf(
20070 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
20080 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
20090 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
200a0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
200b0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
200c0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
200d0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
200e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
200f0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
20100 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
20110 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
20120 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
20130 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
20140 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
20150 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
20160 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
20170 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
20180 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
20190 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
201a0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
201b0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
201c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
201d0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
201e0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
201f0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
20200 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
20210 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
20220 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
20230 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
20240 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
20250 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
20260 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
20270 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
20280 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
20290 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
202a0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
202b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
202c0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
202d0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
202e0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
202f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
20300 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
20310 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20320 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
20330 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
20340 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
20350 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
20360 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
20370 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
20380 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
20390 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
203a0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
203b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
203c0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
203d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
203e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
203f0 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
20400 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
20410 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
20420 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
20430 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
20440 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
20450 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
20460 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
20470 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
20480 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
20490 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
204a0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
204b0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
204c0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
204d0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
204e0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
204f0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
20500 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
20510 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
20520 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
20530 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
20540 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
20550 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
20560 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
20570 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
20580 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
20590 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
205a0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
205b0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
205c0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
205d0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
205e0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
205f0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
20600 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
20610 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
20620 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
20630 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
20640 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
20650 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
20660 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
20670 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
20680 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
20690 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
206a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
206b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
206c0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
206d0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
206e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
206f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20700 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
20710 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
20720 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20730 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
20740 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
20750 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
20760 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20770 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
20780 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
20790 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
207a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
207b0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
207c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
207d0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
207e0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
207f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
20800 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
20810 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
20820 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20830 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
20840 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
20850 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
20860 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
20870 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
20880 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
20890 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
208a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
208b0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
208c0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
208d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
208e0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
208f0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
20900 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
20910 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
20920 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
20930 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
20940 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20950 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
20960 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
20970 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20980 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
20990 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
209a0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
209b0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
209c0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
209d0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
209e0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
209f0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
20a00 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
20a10 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
20a20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
20a30 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
20a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
20a50 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20a70 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
20a80 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
20a90 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
20aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20ab0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
20ac0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
20ad0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
20ae0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
20af0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20b00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
20b10 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
20b20 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
20b30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20b40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20b60 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
20b70 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
20b80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20b90 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
20ba0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
20bb0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
20bc0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
20bd0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
20be0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
20bf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
20c00 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
20c10 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
20c20 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
20c30 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
20c40 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
20c50 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
20c60 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20c70 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
20c80 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
20c90 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
20ca0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
20cb0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
20cc0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
20cd0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
20ce0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
20cf0 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
20d00 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
20d10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
20d20 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
20d30 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
20d40 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
20d50 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20d60 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
20d70 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
20d80 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20d90 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
20da0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20db0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20dc0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
20dd0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
20de0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20df0 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
20e00 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
20e10 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
20e20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
20e30 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
20e40 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
20e50 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
20e60 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
20e70 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
20e80 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
20e90 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
20ea0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
20eb0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
20ec0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
20ed0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
20ee0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
20ef0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
20f00 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
20f10 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
20f20 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
20f30 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
20f40 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
20f50 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
20f60 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
20f70 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
20f80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
20f90 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
20fa0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
20fb0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20fc0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
20fd0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
20fe0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
20ff0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
21000 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
21010 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
21020 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
21030 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
21040 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
21050 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
21060 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
21070 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
21080 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
21090 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
210a0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
210b0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
210c0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
210d0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
210e0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
210f0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
21100 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
21110 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
21120 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
21130 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
21140 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
21150 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
21160 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
21170 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
21180 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
21190 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
211a0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
211b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
211c0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
211d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
211e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
211f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
21200 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
21210 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
21220 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
21230 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
21240 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
21250 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
21260 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
21270 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
21280 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
21290 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
212a0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
212b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
212c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
212d0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
212e0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
212f0 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
21300 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
21310 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
21320 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
21330 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
21340 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
21350 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
21360 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
21370 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
21380 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
21390 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
213a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
213b0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
213c0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
213d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
213e0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
213f0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
21400 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
21410 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
21420 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
21430 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
21440 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21450 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
21460 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
21470 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
21480 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
21490 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
214a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
214b0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
214c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
214d0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
214e0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
214f0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
21500 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
21510 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
21520 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
21530 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
21540 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21550 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
21560 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
21570 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
21580 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
21590 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
215a0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
215b0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
215c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
215d0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
215e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
215f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21600 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
21610 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
21620 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
21630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21640 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
21650 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
21660 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
21670 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
21680 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
21690 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
216a0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
216b0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
216c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
216d0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
216e0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
216f0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
21700 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
21710 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21720 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
21730 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
21740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
21750 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21760 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
21770 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
21780 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
21790 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
217a0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
217b0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
217c0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
217d0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
217e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
217f0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
21800 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
21810 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21820 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
21830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21840 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
21850 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
21860 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
21870 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
21880 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
21890 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
218a0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
218b0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
218c0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
218d0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
218e0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
218f0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
21900 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
21910 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
21920 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
21930 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
21940 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
21950 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
21960 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
21970 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
21980 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
21990 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
219a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
219b0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
219c0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
219d0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
219e0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
219f0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
21a00 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
21a10 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
21a20 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
21a30 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
21a40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21a50 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
21a60 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
21a70 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
21a80 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
21a90 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
21aa0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
21ab0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
21ac0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
21ad0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
21ae0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
21af0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
21b00 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
21b10 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
21b20 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
21b30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21b40 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
21b50 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
21b60 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
21b70 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
21b80 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
21b90 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
21ba0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
21bb0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
21bc0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
21bd0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
21be0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
21bf0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
21c00 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
21c10 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
21c20 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
21c30 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
21c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
21c50 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
21c60 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
21c70 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
21c80 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ite3.** KEYWORDS
21c90 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  : {authorizer ca
21ca0 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54  llback}.**.** ^T
21cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
21cc0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
21cd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
21ce0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
21cf0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
21d00 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
21d10 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
21d20 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
21d30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21d40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21d50 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
21d60 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
21d70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
21d80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21d90 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
21da0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21db0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
21dc0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
21dd0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
21de0 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  re16()], [sqlite
21df0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21e00 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
21e10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
21e20 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
21e30 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
21e40 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
21e50 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
21e60 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
21e70 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
21e80 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
21e90 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
21ea0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21eb0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
21ec0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
21ed0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
21ee0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
21ef0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
21f00 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
21f10 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
21f20 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
21f30 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
21f40 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
21f50 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
21f60 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
21f70 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
21f80 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
21f90 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
21fa0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
21fb0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
21fc0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
21fd0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
21fe0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
21ff0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
22000 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22010 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
22020 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22030 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
22040 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
22050 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
22060 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
22070 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
22080 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
22090 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
220a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
220b0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
220c0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
220d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
220e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
220f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
22100 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
22110 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
22120 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
22130 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
22140 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
22150 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
22160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22170 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
22180 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
22190 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
221a0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
221b0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
221c0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
221d0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
221e0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
221f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
22200 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22210 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22220 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
22230 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
22240 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
22250 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22260 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
22270 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
22280 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
22290 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
222a0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
222b0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
222c0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
222d0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
222e0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
222f0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
22300 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
22310 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
22320 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
22330 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65  llback are eithe
22340 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
22350 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  or zero-terminat
22360 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68  ed strings.** th
22370 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
22380 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
22390 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
223a0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
223b0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
223c0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
223d0 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f  prepared to enco
223e0 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  unter a NULL poi
223f0 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f  nter in any.** o
22400 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f  f the third thro
22410 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61  ugh the sixth pa
22420 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22430 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
22440 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49  llback..**.** ^I
22450 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
22460 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
22470 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
22480 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
22490 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
224a0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
224b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
224c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
224d0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
224e0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
224f0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
22500 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
22510 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
22520 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
22530 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
22540 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
22550 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
22560 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
22570 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22580 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
22590 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
225a0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
225b0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
225c0 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74  le..** ^When a t
225d0 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63  able is referenc
225e0 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d  ed by a [SELECT]
225f0 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76   but no column v
22600 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74  alues are.** ext
22610 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74  racted from that
22620 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d   table (for exam
22630 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c  ple in a query l
22640 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63  ike.** "SELECT c
22650 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62  ount(*) FROM tab
22660 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c  ") then the [SQL
22670 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72  ITE_READ] author
22680 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
22690 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
226a0 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20   for that table 
226b0 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61  with a column na
226c0 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d  me that is an em
226d0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  pty string..** ^
226e0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
226f0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
22700 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
22710 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
22720 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
22730 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
22740 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
22750 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
22760 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
22770 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
22780 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
22790 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
227a0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
227b0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
227c0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
227d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
227e0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
227f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
22800 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
22810 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
22820 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
22830 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
22840 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
22850 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
22860 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
22870 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
22880 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
22890 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
228a0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
228b0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
228c0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
228d0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
228e0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
228f0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
22900 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
22910 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
22920 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
22930 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
22940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
22950 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
22960 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
22970 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
22980 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
22990 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
229a0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
229b0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
229c0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
229d0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
229e0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
229f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22a00 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
22a10 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
22a20 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
22a30 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
22a40 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
22a50 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
22a60 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
22a70 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
22a80 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
22a90 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
22aa0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
22ab0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
22ac0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22ad0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
22ae0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
22af0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
22b00 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
22b10 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
22b20 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
22b30 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
22b40 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
22b50 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
22b60 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
22b70 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
22b80 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
22b90 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
22ba0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
22bb0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
22bc0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
22bd0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
22be0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
22bf0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
22c00 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
22c10 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
22c20 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
22c30 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
22c40 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
22c50 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
22c60 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
22c70 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
22c80 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
22c90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
22ca0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
22cb0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22cc0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
22cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ce0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22cf0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
22d00 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
22d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22d20 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
22d30 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
22d40 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
22d50 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
22d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22d70 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
22d80 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
22d90 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
22da0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
22db0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
22dc0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
22dd0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
22de0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
22df0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
22e00 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
22e10 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
22e20 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
22e30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22e40 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
22e50 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
22e60 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
22e70 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
22e80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22e90 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22ea0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
22eb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22ec0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
22ed0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
22ee0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
22ef0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
22f00 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
22f10 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
22f20 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
22f30 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
22f40 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
22f50 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
22f60 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
22f70 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
22f80 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
22f90 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
22fa0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
22fb0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
22fc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22fd0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
22fe0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
22ff0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
23000 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23010 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
23020 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
23030 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
23040 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23050 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
23060 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
23070 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
23080 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
23090 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
230a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
230b0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
230c0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
230d0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
230e0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
230f0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
23100 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
23110 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
23120 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23130 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
23140 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23150 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
23160 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
23170 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
23180 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
23190 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
231a0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
231b0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
231c0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
231d0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
231e0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
231f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
23200 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
23210 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
23220 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
23230 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
23240 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
23250 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
23260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23270 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
23280 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
23290 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
232a0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
232b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
232c0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
232d0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
232e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
232f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
23300 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
23310 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
23320 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
23330 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
23340 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
23350 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
23360 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
23370 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23380 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
23390 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
233a0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
233b0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
233c0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
233d0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
233e0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
233f0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
23400 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
23410 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
23420 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
23430 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
23440 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
23450 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
23460 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
23470 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
23480 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
23490 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
234a0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
234b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
234c0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
234d0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
234e0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
234f0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
23500 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
23510 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
23520 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
23530 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
23540 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
23550 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
23560 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
23570 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
23580 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
23590 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
235a0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
235b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
235c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
235d0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
235e0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
235f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
23600 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
23610 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
23620 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
23630 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
23640 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
23650 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
23660 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
23670 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
23680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
236a0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
236b0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
236c0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
236d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
236e0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
236f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
23700 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23720 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
23730 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
23740 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23750 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23770 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
23780 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
23790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
237a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
237b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
237c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
237d0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
237e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
237f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23810 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23820 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
23830 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23860 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
23870 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
23880 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
23890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
238a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
238b0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
238c0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
238d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
238e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
238f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23900 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
23910 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
23920 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23950 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
23960 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
23970 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23980 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
239a0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
239b0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
239c0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
239d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
239e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
239f0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
23a00 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
23a10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23a20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23a40 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
23a50 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
23a60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23a70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23a80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23a90 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
23aa0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
23ab0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23ac0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23ad0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23ae0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
23af0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
23b00 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
23b10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23b20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23b30 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
23b40 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23b50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23b60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23b70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
23b80 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
23b90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23ba0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23bb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23bc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
23bd0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
23be0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
23bf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23c00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23c10 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
23c20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
23c30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23c40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23c50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23c60 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
23c70 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
23c80 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
23c90 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
23ca0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
23cb0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
23cc0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
23cd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23ce0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
23cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23d00 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
23d10 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
23d20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23d30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23d50 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
23d60 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
23d70 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
23d80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23da0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
23db0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
23dc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
23dd0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
23de0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23df0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
23e00 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
23e10 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
23e20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23e40 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
23e50 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
23e60 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
23e70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
23e90 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
23ea0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
23eb0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
23ec0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
23ee0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
23ef0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
23f00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23f10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
23f30 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
23f40 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
23f50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23f60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23f70 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23f80 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
23f90 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
23fa0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
23fb0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23fc0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
23fd0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
23fe0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
23ff0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
24000 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24010 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
24020 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
24030 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
24040 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
24050 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
24060 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
24070 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
24080 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
24090 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
240a0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
240b0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
240c0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
240d0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
240e0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
240f0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
24100 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
24110 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
24120 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24130 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
24140 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
24150 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
24160 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
24170 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
24180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
24190 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
241a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
241b0 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
241c0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
241d0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
241e0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
241f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24200 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
24210 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
24220 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
24230 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
24240 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
24250 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
24260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
24270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
24280 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
24290 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
242a0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
242b0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
242c0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
242d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
242e0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
242f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24300 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
24310 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24320 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24330 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
24340 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
24350 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
24360 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
24370 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
24380 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
24390 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
243a0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
243b0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
243c0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
243d0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
243e0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
243f0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
24400 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
24410 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
24420 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
24430 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
24440 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
24450 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
24460 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
24470 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
24480 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
24490 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
244a0 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
244b0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
244c0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
244d0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
244e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
244f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
24500 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
24510 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
24520 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
24530 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
24540 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
24550 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
24560 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
24570 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
24580 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
24590 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
245a0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
245b0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
245c0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
245d0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
245e0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
245f0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
24600 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
24610 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
24620 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
24630 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
24640 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
24650 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
24660 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
24670 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
24680 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
24690 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
246a0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
246b0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
246c0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
246d0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
246e0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
246f0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
24700 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
24710 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
24720 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
24730 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
24740 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
24750 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
24760 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
24770 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
24780 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
24790 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
247a0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ace(sqlite3*,.  
247b0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
247c0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
247d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
247e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
247f0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
24800 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
24810 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
24820 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
24830 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
24840 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
24850 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
24860 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
24870 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
24880 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
24890 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
248a0 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
248b0 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
248c0 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
248d0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
248e0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
248f0 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
24900 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67 75 6d  ic.  The M argum
24910 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
24920 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
24930 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  X,P)] is an OR-e
24940 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
24950 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
24960 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
24970 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
24980 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
24990 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
249a0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
249b0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
249c0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
249d0 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
249e0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
249f0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
24a00 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
24a10 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
24a20 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
24a30 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
24a40 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
24a50 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
24a60 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
24a70 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
24a80 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
24a90 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
24aa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
24ab0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24ac0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
24ad0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
24ae0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24af0 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
24b00 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
24b10 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
24b20 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
24b30 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
24b40 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
24b50 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
24b60 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24b70 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
24b80 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
24b90 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
24ba0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
24bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bc0 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
24bd0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
24be0 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
24bf0 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
24c00 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
24c10 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
24c20 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
24c30 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
24c40 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
24c50 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
24c60 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24c80 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24c90 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
24ca0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24cb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
24cc0 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
24cd0 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
24ce0 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
24cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d00 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
24d10 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
24d20 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
24d30 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
24d40 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
24d50 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
24d60 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
24d70 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
24d80 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
24d90 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
24da0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
24db0 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
24dc0 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
24dd0 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
24de0 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
24df0 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
24e00 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
24e10 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
24e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24e30 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
24e40 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
24e50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
24e60 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24e70 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
24e80 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
24e90 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
24ea0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
24eb0 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
24ec0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
24ed0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
24ee0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
24ef0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24f00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24f20 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
24f30 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
24f40 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
24f50 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
24f60 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
24f70 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
24f80 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
24f90 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
24fa0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
24fb0 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
24fc0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24fd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24fe0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
24ff0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
25000 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
25010 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
25020 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
25030 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
25040 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
25050 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
25060 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
25070 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
25080 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
25090 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
250a0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
250b0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
250c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
250d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
250e0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
250f0 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
25100 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
25110 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
25120 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
25130 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
25140 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
25150 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
25160 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
25170 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
25180 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
25190 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
251a0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
251b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
251c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
251d0 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
251e0 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
251f0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
25200 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
25210 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25220 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
25230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
25240 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
25250 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
25260 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
25270 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
25280 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
25290 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
252a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
252b0 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
252c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
252d0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
252e0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
252f0 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
25300 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
25310 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
25320 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
25330 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
25340 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
25350 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
25360 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
25370 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
25380 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
25390 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
253a0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
253b0 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
253c0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
253d0 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
253e0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
253f0 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
25400 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
25410 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
25420 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
25430 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
25440 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
25450 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
25460 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
25470 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
25480 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
25490 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
254a0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
254b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
254c0 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
254d0 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
254e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
254f0 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
25500 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
25510 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
25520 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
25530 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
25540 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
25550 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
25560 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
25570 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
25580 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
25590 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
255a0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
255b0 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
255c0 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
255d0 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
255e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
255f0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
25600 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
25610 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
25620 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
25630 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
25640 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
25650 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
25660 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
25670 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
25680 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
25690 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
256a0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
256b0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
256c0 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
256d0 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
256e0 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
256f0 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
25700 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
25710 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25720 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
25730 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
25740 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
25750 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
25760 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
25770 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
25780 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
25790 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
257a0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
257b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
257c0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
257d0 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
257e0 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
257f0 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
25800 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
25810 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
25820 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
25830 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
25840 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
25850 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25860 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
25870 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
25880 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
25890 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
258a0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
258b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
258c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
258d0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
258e0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
258f0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
25900 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
25910 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
25920 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
25930 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
25940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25950 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
25960 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
25970 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
25980 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
25990 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
259a0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
259b0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
259c0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
259d0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
259e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
259f0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
25a00 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
25a10 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
25a20 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
25a30 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
25a40 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
25a50 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
25a60 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
25a70 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
25a80 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
25a90 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
25aa0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
25ab0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
25ac0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
25ad0 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
25ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
25af0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
25b00 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
25b10 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
25b20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
25b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25b40 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
25b50 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25b60 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
25b70 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
25b80 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
25b90 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
25ba0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
25bb0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
25bc0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
25bd0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
25be0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
25bf0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
25c00 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
25c10 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
25c20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
25c30 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
25c40 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
25c50 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
25c60 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
25c70 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25c80 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
25c90 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
25ca0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
25cb0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
25cc0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25cd0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
25ce0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
25cf0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
25d00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
25d10 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
25d20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
25d30 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25d40 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
25d50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25d60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
25d70 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
25d80 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
25d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
25da0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
25db0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
25dc0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
25dd0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
25de0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
25df0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
25e00 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
25e10 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
25e20 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
25e30 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
25e40 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
25e50 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
25e60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
25e70 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
25e80 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
25e90 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
25ea0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
25eb0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25ec0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
25ed0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
25ee0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
25ef0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
25f00 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25f10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
25f20 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
25f30 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
25f40 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
25f50 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
25f60 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
25f70 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
25f80 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
25f90 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
25fa0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
25fb0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
25fc0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
25fd0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
25fe0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
25ff0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
26000 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
26010 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
26020 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
26030 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
26040 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
26050 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
26060 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
26070 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
26080 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26090 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
260a0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
260b0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
260c0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
260d0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
260e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
260f0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
26100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
26110 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
26120 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
26130 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
26140 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
26150 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
26160 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
26170 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
26180 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
26190 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
261a0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
261b0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
261c0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
261d0 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
261e0 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
261f0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
26200 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
26210 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
26220 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
26230 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
26240 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
26250 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
26260 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
26270 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
26280 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26290 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
262a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
262b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
262c0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
262d0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
262e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
262f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26300 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
26310 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
26320 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
26330 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
26340 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
26350 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
26360 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
26370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26380 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
26390 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
263a0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
263b0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
263c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
263d0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
263e0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
263f0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
26400 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
26410 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
26420 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
26430 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
26440 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
26450 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
26460 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
26470 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
26480 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
26490 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
264a0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
264b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
264c0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
264d0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
264e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
264f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
26500 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
26510 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
26520 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
26530 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
26540 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
26550 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
26560 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26570 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
26580 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
26590 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
265a0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
265b0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
265c0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
265d0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
265e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
265f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26600 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26610 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
26620 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
26630 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
26640 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
26650 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
26660 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
26670 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
26680 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
26690 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
266a0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
266b0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
266c0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
266d0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
266e0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
266f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26700 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
26710 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
26720 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
26730 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
26740 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
26750 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
26760 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
26770 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
26780 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
26790 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
267a0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
267b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
267c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
267d0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
267e0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
267f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
26800 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26810 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
26820 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
26830 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
26840 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
26850 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
26860 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
26870 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
26880 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
26890 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
268a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
268b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
268c0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
268d0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
268e0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
268f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26900 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
26910 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
26920 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
26930 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
26940 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
26950 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
26960 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
26970 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
26980 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
26990 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
269a0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
269b0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
269c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
269d0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
269e0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
269f0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
26a00 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
26a10 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
26a20 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
26a30 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
26a40 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
26a50 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
26a60 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26a70 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26a80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26a90 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
26aa0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
26ab0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26ac0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
26ad0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26ae0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
26af0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
26b00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
26b10 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
26b20 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
26b30 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
26b40 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
26b50 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
26b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
26b70 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
26b80 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
26b90 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
26ba0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
26bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
26bc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26bd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26be0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
26bf0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
26c00 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
26c10 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
26c20 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
26c30 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
26c40 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
26c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
26c60 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
26c70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26c80 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
26c90 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
26ca0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
26cb0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
26cc0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
26cd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26ce0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
26cf0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
26d00 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
26d10 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
26d20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
26d30 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
26d40 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
26d50 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
26d60 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
26d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26d80 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
26d90 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
26da0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
26db0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
26dc0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
26dd0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
26de0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
26df0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
26e00 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
26e10 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
26e20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26e30 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
26e40 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
26e50 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
26e60 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
26e70 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
26e80 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
26e90 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
26ea0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
26eb0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
26ec0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
26ed0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
26ee0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
26ef0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
26f00 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
26f10 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
26f20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
26f30 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
26f40 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
26f50 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
26f60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26f70 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
26f80 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
26f90 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
26fa0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
26fb0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
26fc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
26fd0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
26fe0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
26ff0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
27000 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
27010 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
27020 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
27030 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
27040 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
27050 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
27060 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
27070 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
27080 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
27090 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
270a0 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69 72   set in the thir
270b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
270c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
270d0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
270e0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
270f0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
27100 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27110 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
27120 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
27130 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
27140 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
27150 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
27160 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
27170 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  ..** URI filenam
27180 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
27190 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
271a0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
271b0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
271c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
271d0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
271e0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
271f0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
27200 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
27210 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
27220 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
27230 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
27240 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
27250 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
27260 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
27270 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
27280 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
27290 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
272a0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
272b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
272c0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
272d0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
272e0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
272f0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
27300 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
27310 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
27320 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
27330 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
27340 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
27350 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
27360 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
27370 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
27380 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
27390 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
273a0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
273b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
273c0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
273d0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
273e0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
273f0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
27400 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
27410 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
27420 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
27430 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
27440 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
27450 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
27460 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
27470 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
27480 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
27490 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
274a0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
274b0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
274c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
274d0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
274e0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
274f0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
27500 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
27510 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
27520 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
27530 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
27540 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
27550 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
27560 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
27570 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
27580 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
27590 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
275a0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
275b0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
275c0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
275d0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
275e0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
275f0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
27600 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
27610 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
27620 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
27630 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
27640 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
27650 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
27660 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
27670 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
27680 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
27690 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
276a0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
276b0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
276c0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
276d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
276e0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
276f0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
27700 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
27710 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
27720 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
27730 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
27740 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
27750 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
27760 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
27770 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
27780 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
27790 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
277a0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
277b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
277c0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
277d0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
277e0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
277f0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
27800 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
27810 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
27820 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
27830 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
27840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27860 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
27870 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
27880 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
27890 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
278a0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
278b0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
278c0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
278d0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
278e0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
278f0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
27900 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
27910 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
27920 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
27930 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
27940 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
27950 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
27960 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
27970 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
27980 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
27990 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
279a0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
279b0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
279c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
279d0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
279e0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
279f0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
27a00 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
27a10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27a20 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
27a30 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
27a40 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27a50 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
27a60 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
27a70 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
27a80 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
27a90 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
27aa0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
27ab0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27ac0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
27ad0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
27ae0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
27af0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
27b00 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
27b10 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
27b20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
27b30 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
27b40 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
27b50 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
27b60 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
27b70 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
27b80 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
27b90 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
27ba0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
27bb0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
27bc0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
27bd0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
27be0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
27bf0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
27c00 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
27c10 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
27c20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27c30 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
27c40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
27c50 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
27c60 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27c70 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27c80 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
27c90 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
27ca0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
27cb0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
27cc0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27cd0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
27ce0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27cf0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
27d00 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
27d10 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
27d20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27d30 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
27d40 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
27d50 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
27d60 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
27d70 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
27d80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27d90 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
27da0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
27db0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
27dc0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
27dd0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
27de0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
27df0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
27e00 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
27e10 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
27e20 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
27e30 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
27e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
27e50 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
27e60 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27e70 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
27e80 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
27e90 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
27ea0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
27eb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
27ec0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
27ed0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
27ee0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
27ef0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
27f00 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
27f10 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
27f20 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
27f30 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
27f40 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
27f50 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
27f60 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
27f70 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
27f80 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
27f90 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
27fa0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
27fb0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
27fc0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
27fd0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
27fe0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
27ff0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
28000 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
28010 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
28020 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
28030 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
28040 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
28050 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
28060 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
28070 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
28080 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
28090 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
280a0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
280b0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
280c0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
280d0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
280e0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
280f0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
28100 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
28110 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
28120 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
28130 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
28140 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
28150 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
28160 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
28170 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
28180 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
28190 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
281a0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
281b0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
281c0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
281d0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
281e0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
281f0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
28200 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
28210 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
28220 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
28230 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
28240 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
28250 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
28260 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
28270 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
28280 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
28290 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
282a0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
282b0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
282c0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
282d0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
282e0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
282f0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
28300 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
28310 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
28320 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
28330 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
28340 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
28350 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
28360 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
28370 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
28380 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
28390 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
283a0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
283b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
283c0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
283d0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
283e0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
283f0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
28400 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
28410 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
28420 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
28430 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
28440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
28450 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
28460 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
28470 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
28480 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
28490 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
284a0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
284b0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
284c0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
284d0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
284e0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
284f0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
28500 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
28510 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
28520 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
28530 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
28540 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
28550 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
28560 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
28570 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
28580 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
28590 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
285a0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
285b0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
285c0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
285d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
285e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
285f0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
28600 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
28610 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
28620 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
28630 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
28640 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
28650 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
28660 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
28670 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
28680 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
28690 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
286a0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
286b0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
286c0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
286d0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
286e0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
286f0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
28700 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
28710 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
28720 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
28730 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
28740 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
28750 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
28760 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
28770 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
28780 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
28790 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
287a0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
287b0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
287c0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
287d0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
287e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
287f0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
28800 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
28810 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28820 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
28830 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
28840 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
28850 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
28860 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
28870 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
28880 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
28890 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
288a0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
288b0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
288c0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
288d0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
288e0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
288f0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
28900 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
28910 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
28920 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
28930 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
28940 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
28950 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
28960 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
28970 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
28980 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
28990 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
289a0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
289b0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
289c0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
289d0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
289e0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
289f0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
28a00 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
28a10 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
28a20 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
28a30 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
28a40 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28a50 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
28a60 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
28a70 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
28a80 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
28a90 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
28aa0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28ab0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
28ac0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
28ad0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
28ae0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
28af0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
28b00 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
28b10 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
28b20 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
28b30 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
28b40 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
28b50 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
28b60 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
28b70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
28b80 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
28b90 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
28ba0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28bb0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
28bc0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
28bd0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
28be0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
28bf0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
28c00 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
28c10 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
28c20 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
28c30 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
28c40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28c50 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
28c60 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
28c70 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
28c80 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
28c90 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
28ca0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
28cb0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
28cc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
28cd0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
28ce0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
28cf0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
28d00 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
28d10 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
28d20 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
28d30 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
28d40 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
28d50 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
28d60 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
28d70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
28d80 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
28d90 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
28da0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
28db0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
28dc0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
28dd0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
28de0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
28df0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
28e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
28e10 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
28e20 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
28e30 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
28e40 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
28e50 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
28e60 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
28e70 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
28e80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28e90 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
28ea0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
28eb0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
28ec0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28ed0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
28ee0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
28ef0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
28f00 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
28f10 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
28f20 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
28f30 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
28f40 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
28f50 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28f60 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28f70 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
28f80 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
28f90 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
28fa0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
28fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28fc0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
28fd0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28fe0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
28ff0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
29000 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
29010 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
29020 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
29030 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
29040 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29050 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
29060 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
29070 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
29080 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
29090 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
290a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
290b0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
290c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
290d0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
290e0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
290f0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
29100 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
29110 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
29120 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
29130 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
29140 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
29150 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
29160 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
29170 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
29180 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
29190 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
291a0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
291b0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
291c0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
291d0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
291e0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
291f0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
29200 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
29210 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
29220 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
29230 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
29240 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
29250 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
29260 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
29270 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
29280 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
29290 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
292a0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
292b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
292c0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
292d0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
292e0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
292f0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
29300 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
29310 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
29320 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
29330 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29340 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
29350 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
29360 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
29370 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
29380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
29390 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
293a0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
293b0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
293c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
293d0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
293e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
293f0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
29400 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
29410 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
29420 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
29430 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
29440 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
29450 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
29460 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
29470 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29490 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
294a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
294b0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
294c0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
294d0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
294e0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
294f0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
29500 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
29510 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
29520 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
29530 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29540 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
29550 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
29560 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
29570 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29580 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
29590 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
295a0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
295b0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
295c0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
295d0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
295e0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
295f0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
29600 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
29610 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
29620 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
29630 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
29640 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
29650 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29660 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
29670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29680 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
29690 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
296a0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
296b0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
296c0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
296d0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
296e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
296f0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
29700 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
29710 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
29720 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
29730 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
29740 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
29750 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
29760 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
29770 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
29780 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
29790 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
297a0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
297b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
297c0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
297d0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
297e0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
297f0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
29800 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29810 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
29820 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
29830 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
29840 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
29850 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29860 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
29870 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
29880 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
29890 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
298a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
298b0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
298c0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
298d0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
298e0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
298f0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
29900 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
29910 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
29920 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
29930 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
29940 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
29950 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
29960 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
29970 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
29980 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
29990 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
299a0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
299b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
299c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
299d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
299e0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
299f0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
29a00 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
29a10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
29a20 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
29a30 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
29a40 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
29a50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
29a60 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
29a70 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
29a80 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
29a90 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
29aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29ab0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
29ac0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
29ad0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
29ae0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
29af0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
29b00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
29b10 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
29b20 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
29b30 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
29b40 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
29b50 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   The values retu
29b60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
29b70 65 72 72 63 6f 64 65 28 29 20 61 6e 64 2f 6f 72  errcode() and/or
29b80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 74 65  .** sqlite3_exte
29b90 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 20 6d  nded_errcode() m
29ba0 69 67 68 74 20 63 68 61 6e 67 65 20 77 69 74 68  ight change with
29bb0 20 65 61 63 68 20 41 50 49 20 63 61 6c 6c 2e 0a   each API call..
29bc0 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 65 72 65  ** Except, there
29bd0 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 65 72 66   are some interf
29be0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 67 75  aces that are gu
29bf0 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65 76 65  aranteed to neve
29c00 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  r.** change the 
29c10 76 61 6c 75 65 20 6f 66 20 74 68 65 20 65 72 72  value of the err
29c20 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 65 72  or code.  The er
29c30 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 65 72 76  ror-code preserv
29c40 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ing.** interface
29c50 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  s are:.**.** <ul
29c60 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
29c70 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c  3_errcode().** <
29c80 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 78 74 65  li> sqlite3_exte
29c90 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
29ca0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
29cb0 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20  rrmsg().** <li> 
29cc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
29cd0 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  ().** </ul>.**.*
29ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
29cf0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
29d00 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
29d10 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
29d20 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
29d30 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
29d40 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
29d50 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29d60 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
29d70 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29d80 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29d90 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29da0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29db0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
29dc0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
29dd0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
29de0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
29df0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
29e00 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
29e10 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
29e20 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
29e30 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
29e40 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
29e50 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
29e60 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
29e70 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
29e80 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
29e90 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
29ea0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
29eb0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
29ec0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
29ed0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
29ee0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
29ef0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
29f00 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
29f10 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
29f20 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
29f30 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
29f40 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
29f50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
29f60 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
29f70 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
29f80 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
29f90 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
29fa0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
29fb0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
29fc0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
29fd0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
29fe0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
29ff0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
2a000 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
2a010 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
2a020 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
2a030 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
2a040 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
2a050 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
2a060 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
2a070 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
2a080 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
2a090 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
2a0a0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
2a0b0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
2a0c0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
2a0d0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
2a0e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a0f0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
2a100 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
2a110 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
2a120 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
2a130 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
2a140 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
2a150 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
2a160 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
2a170 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
2a180 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
2a190 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
2a1a0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
2a1b0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
2a1c0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
2a1d0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
2a1e0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
2a1f0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
2a200 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
2a210 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
2a220 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
2a230 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2a240 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
2a250 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
2a260 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
2a270 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
2a280 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
2a290 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a2a0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
2a2b0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
2a2c0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
2a2d0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
2a2e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
2a2f0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
2a300 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a310 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
2a320 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
2a330 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
2a340 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
2a350 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2a360 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2a370 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2a380 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
2a390 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
2a3a0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
2a3b0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
2a3c0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
2a3d0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
2a3e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
2a3f0 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
2a400 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
2a410 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
2a420 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
2a430 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
2a440 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
2a450 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
2a460 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
2a470 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
2a480 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2a490 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
2a4a0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
2a4b0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
2a4c0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
2a4d0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
2a4e0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
2a4f0 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
2a500 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
2a510 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
2a520 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
2a530 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
2a540 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
2a550 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2a560 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
2a570 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
2a580 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
2a590 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
2a5a0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2a5b0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
2a5c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
2a5d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
2a5e0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
2a5f0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
2a600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
2a610 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
2a620 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
2a630 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
2a640 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2a650 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
2a660 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
2a670 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2a680 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2a690 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2a6a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
2a6b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
2a6c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
2a6d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
2a6e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
2a6f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
2a700 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2a710 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
2a720 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a730 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
2a740 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
2a750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a760 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
2a770 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2a780 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
2a790 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
2a7a0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
2a7b0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
2a7c0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
2a7d0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
2a7e0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
2a7f0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
2a800 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a810 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2a820 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
2a830 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
2a840 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
2a850 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
2a860 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
2a870 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
2a880 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
2a890 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
2a8a0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
2a8b0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
2a8c0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
2a8d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2a8e0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
2a8f0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
2a900 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2a910 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
2a920 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
2a930 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
2a940 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
2a950 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
2a960 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
2a970 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
2a980 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
2a990 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
2a9a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
2a9b0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
2a9c0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
2a9d0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
2a9e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
2a9f0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
2aa00 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
2aa10 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
2aa20 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
2aa30 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
2aa40 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
2aa50 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
2aa60 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
2aa70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
2aa80 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
2aa90 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
2aaa0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
2aab0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
2aac0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2aad0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
2aae0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
2aaf0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2ab00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2ab10 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
2ab20 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
2ab30 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
2ab40 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
2ab50 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
2ab60 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
2ab70 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
2ab80 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
2ab90 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
2aba0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2abb0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
2abc0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
2abd0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
2abe0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
2abf0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
2ac00 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
2ac10 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
2ac20 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
2ac30 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
2ac40 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
2ac50 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
2ac60 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
2ac70 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
2ac80 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
2ac90 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
2aca0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
2acb0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
2acc0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
2acd0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
2ace0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
2acf0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
2ad00 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
2ad10 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
2ad20 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
2ad30 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
2ad40 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
2ad50 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
2ad60 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
2ad70 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
2ad80 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
2ad90 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
2ada0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
2adb0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
2adc0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
2add0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
2ade0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
2adf0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
2ae00 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
2ae10 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
2ae20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
2ae30 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
2ae40 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
2ae50 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
2ae60 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
2ae70 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2ae80 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
2ae90 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
2aea0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
2aeb0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
2aec0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
2aed0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
2aee0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
2aef0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
2af00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2af10 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
2af20 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
2af30 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
2af40 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
2af50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2af60 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
2af70 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
2af80 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
2af90 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
2afa0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
2afb0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2afc0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2afd0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
2afe0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
2aff0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
2b000 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
2b010 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
2b020 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
2b030 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
2b040 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
2b050 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
2b060 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
2b070 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2b080 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
2b090 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
2b0a0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
2b0b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2b0c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b0d0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2b0e0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
2b0f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2b100 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
2b110 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
2b120 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
2b130 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
2b140 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b150 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
2b160 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b170 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
2b180 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b190 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2b1a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2b1b0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
2b1c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b1d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
2b1e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2b1f0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
2b200 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b210 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2b220 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
2b230 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
2b240 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
2b250 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2b260 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
2b270 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b280 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
2b290 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
2b2a0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
2b2b0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
2b2c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b2d0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
2b2e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b2f0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
2b300 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b310 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2b320 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
2b330 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
2b340 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b350 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2b360 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
2b370 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b380 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2b390 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
2b3a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b3b0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
2b3c0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
2b3d0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
2b3e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2b3f0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
2b400 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b410 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
2b420 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b430 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
2b440 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
2b450 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2b460 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
2b470 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
2b480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
2b490 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
2b4a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
2b4b0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
2b4c0 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
2b4d0 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
2b4e0 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2b4f0 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2b500 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2b510 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2b520 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2b530 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2b540 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b550 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2b560 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2b570 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2b580 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2b590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b5a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2b5b0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2b5c0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2b5d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2b5e0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2b5f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2b600 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2b610 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2b620 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2b630 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2b640 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2b650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b660 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2b670 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2b680 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2b690 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2b6a0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b6b0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2b6c0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2b6d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2b6e0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2b6f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2b700 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2b710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2b720 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2b730 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b740 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2b750 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2b760 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2b770 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2b780 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2b790 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2b7a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b7b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2b7c0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2b7d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2b7e0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2b7f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b800 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2b810 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2b820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b830 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2b840 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2b850 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b860 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2b870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b880 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2b890 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2b8a0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2b8b0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2b8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b8d0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2b8e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2b8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b900 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2b910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2b920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b930 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2b940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b950 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b960 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2b970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b980 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2b990 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b9a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2b9b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2b9c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b9d0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2b9e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2b9f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2ba00 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2ba10 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2ba20 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2ba30 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2ba40 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2ba50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2ba60 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2ba70 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2ba80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2ba90 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2baa0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2bab0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2bac0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2bad0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2bae0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2baf0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2bb00 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2bb10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bb20 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2bb30 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2bb40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2bb50 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  pare Flags.**.**
2bb60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2bb70 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2bb80 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62  flags that can b
2bb90 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  e passed into.**
2bba0 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72   "prepFlags" par
2bbb0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73  ameter of the [s
2bbc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bbd0 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  3()] and.** [sql
2bbe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bbf0 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e  3()] interfaces.
2bc00 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73  .**.** New flags
2bc10 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2bc20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2bc30 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2bc40 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2bc50 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2bc60 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  STENT]] ^(<dt>SQ
2bc70 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2bc80 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  SISTENT</dt>.** 
2bc90 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2bca0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2bcb0 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74  T flag is a hint
2bcc0 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c   to the query pl
2bcd0 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  anner.** that th
2bce0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2bcf0 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74  ment will be ret
2bd00 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67  ained for a long
2bd10 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f   time and.** pro
2bd20 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e  bably reused man
2bd30 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68  y times.)^ ^With
2bd40 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b  out this flag, [
2bd50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bd60 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  v3()].** and [sq
2bd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bd80 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61  v3()] assume tha
2bd90 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2bda0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a  tatement will .*
2bdb0 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f  * be used just o
2bdc0 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61  nce or at most a
2bdd0 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74   few times and t
2bde0 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
2bdf0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2be00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61  finalize()] rela
2be10 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65  tively soon. The
2be20 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2be30 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20  ntation acts.** 
2be40 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20  on this hint by 
2be50 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65  avoiding the use
2be60 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d   of [lookaside m
2be70 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74  emory] so as not
2be80 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74   to.** deplete t
2be90 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65  he limited store
2bea0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
2beb0 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72  mory. Future ver
2bec0 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69  sions of.** SQLi
2bed0 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68  te may act on th
2bee0 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e  is hint differen
2bef0 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  tly..** </dl>.*/
2bf00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bf10 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2bf20 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2bf30 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2bf40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2bf50 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2bf60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2bf70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2bf80 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2bf90 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2bfa0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2bfb0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2bfc0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2bfd0 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2bfe0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2bff0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2c000 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2c010 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2c020 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2c030 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2c040 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2c050 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2c060 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2c070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c080 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2c090 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2c0a0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2c0b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c0c0 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2c0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c0e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2c0f0 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2c100 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2c110 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c120 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2c130 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2c140 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2c150 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2c160 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2c170 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2c180 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2c190 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2c1a0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2c1b0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2c1c0 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2c1d0 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2c1e0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2c1f0 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2c200 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2c210 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2c220 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2c230 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2c240 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2c250 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2c260 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2c270 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2c280 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2c290 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c2a0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2c2b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c2c0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2c2d0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2c2e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2c2f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2c300 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2c310 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2c320 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2c330 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2c340 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2c350 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2c360 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2c370 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2c380 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2c390 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2c3a0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2c3b0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2c3c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2c3d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2c3e0 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2c3f0 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2c400 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2c410 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2c420 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2c430 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2c440 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2c450 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c460 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2c470 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2c480 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2c490 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2c4a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2c4b0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2c4c0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2c4d0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2c4e0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2c4f0 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2c500 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2c510 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2c520 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2c530 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2c540 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2c550 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2c560 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2c570 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2c580 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2c590 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2c5a0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2c5b0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2c5c0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2c5d0 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2c5e0 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2c5f0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2c600 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2c610 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c620 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2c630 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2c640 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2c650 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2c660 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2c670 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2c680 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2c690 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2c6a0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2c6b0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2c6c0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2c6d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2c6e0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2c6f0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2c700 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2c710 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2c720 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2c730 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2c740 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2c750 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2c760 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2c770 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2c780 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2c790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2c7a0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2c7b0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2c7c0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2c7d0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2c7e0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2c7f0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2c800 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2c810 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2c820 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2c830 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2c840 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2c850 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2c860 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2c870 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2c880 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2c890 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2c8a0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2c8b0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2c8c0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2c8d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c8e0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2c8f0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2c900 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2c910 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2c920 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2c930 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2c940 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2c950 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2c960 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2c970 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2c980 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2c990 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2c9a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c9b0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2c9c0 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2c9d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c9e0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2c9f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2ca00 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2ca10 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2ca20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2ca30 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2ca40 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2ca50 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2ca60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ca70 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2ca80 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2ca90 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2caa0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2cab0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2cac0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2cad0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2cae0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2caf0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2cb00 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2cb10 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2cb20 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2cb30 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2cb40 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2cb50 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2cb60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2cb70 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2cb80 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2cb90 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2cba0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2cbb0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2cbc0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2cbd0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2cbe0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2cbf0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2cc00 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2cc10 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2cc20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2cc30 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cc40 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2cc50 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2cc60 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2cc70 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2cc80 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2cc90 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2cca0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2ccb0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2ccc0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2ccd0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2cce0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2ccf0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2cd00 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2cd10 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2cd20 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2cd30 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2cd40 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2cd50 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2cd60 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2cd70 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2cd80 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2cd90 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2cda0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2cdb0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2cdc0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2cdd0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2cde0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2cdf0 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2ce00 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2ce10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ce20 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2ce30 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2ce40 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2ce50 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2ce60 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2ce70 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2ce80 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2ce90 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2cea0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2ceb0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2cec0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2ced0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2cee0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2cef0 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2cf00 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2cf10 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2cf20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2cf30 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2cf40 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2cf50 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2cf60 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2cf70 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2cf80 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2cf90 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2cfa0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2cfb0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2cfc0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2cfd0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2cfe0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2cff0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2d000 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2d010 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2d020 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2d030 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2d040 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2d050 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2d060 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2d070 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2d080 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2d090 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2d0a0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2d0b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2d0c0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2d0d0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2d0e0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2d0f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d100 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2d110 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2d120 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2d130 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2d140 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2d150 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2d160 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2d170 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </ol>.**.** <p>^
2d180 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d190 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2d1a0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2d1b0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2d1c0 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2d1d0 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2d1e0 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2d1f0 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2d200 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2d210 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2d220 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2d230 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2d240 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2d250 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2d260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d270 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2d280 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2d290 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2d2a0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2d2b0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2d2c0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2d2d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d2e0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2d2f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2d300 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2d310 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2d320 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2d330 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2d340 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2d350 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2d360 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2d370 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2d380 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2d390 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2d3a0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2d3b0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2d3c0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2d3d0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2d3e0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2d3f0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2d400 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2d410 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2d420 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2d430 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d440 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d450 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d460 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2d470 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d480 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2d490 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2d4a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2d4b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2d4c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2d4d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2d4e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2d4f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2d500 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2d510 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d520 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2d530 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2d540 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2d550 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2d560 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d570 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2d580 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2d590 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2d5a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2d5b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2d5c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2d5d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2d5e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d5f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d600 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d610 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d620 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2d630 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2d640 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2d650 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2d660 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2d670 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2d680 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2d690 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2d6a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2d6b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2d6c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2d6d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2d6e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2d6f0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2d700 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2d710 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d720 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2d730 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2d740 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2d750 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2d760 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2d770 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2d780 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2d790 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2d7a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2d7b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2d7c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2d7d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2d7e0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d7f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2d800 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2d810 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2d820 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2d830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d840 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2d850 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2d860 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2d870 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2d880 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2d890 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2d8a0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2d8b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2d8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2d8d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2d8e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2d8f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2d900 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2d910 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2d920 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2d930 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2d940 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2d950 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2d960 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2d970 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2d980 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2d990 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d9a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d9b0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d9c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2d9d0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d9e0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2d9f0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2da00 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2da10 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2da20 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2da30 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2da40 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2da50 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2da60 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2da70 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2da80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2da90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2daa0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2dab0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2dac0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2dad0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2dae0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2daf0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2db00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2db10 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2db20 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2db30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2db40 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2db50 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2db60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2db70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2db80 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2db90 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2dba0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2dbb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dbc0 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2dbd0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2dbe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2dbf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dc00 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2dc10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2dc20 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2dc30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2dc40 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2dc50 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2dc60 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2dc70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2dc80 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2dc90 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2dca0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2dcb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dcc0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2dcd0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2dce0 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2dcf0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2dd00 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2dd10 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2dd20 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2dd30 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2dd40 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2dd50 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2dd60 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2dd70 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2dd80 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2dd90 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2dda0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2ddb0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2ddc0 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2ddd0 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2dde0 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2ddf0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2de00 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2de10 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2de20 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2de30 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2de40 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2de50 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2de60 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2de70 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2de80 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2de90 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2dea0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2deb0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2dec0 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2ded0 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2dee0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2def0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2df00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2df10 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2df20 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2df30 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2df40 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2df50 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2df60 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2df70 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2df80 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2df90 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2dfa0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2dfb0 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2dfc0 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2dfd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2dfe0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2dff0 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2e000 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2e010 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2e020 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2e030 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2e040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2e050 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2e060 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2e070 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2e080 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2e090 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2e0a0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2e0b0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2e0c0 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2e0d0 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2e0e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2e0f0 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2e100 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2e110 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2e120 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2e130 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2e140 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2e150 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e160 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e170 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e180 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2e190 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2e1a0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2e1b0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2e1c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e1d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e1e0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2e1f0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2e200 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2e210 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2e220 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2e230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e240 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2e250 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2e260 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2e270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2e280 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2e290 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2e2a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e2b0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2e2c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2e2d0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2e2e0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2e2f0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2e300 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2e310 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2e320 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2e330 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2e340 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2e350 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2e360 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2e370 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2e380 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2e390 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2e3a0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2e3b0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2e3c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2e3d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2e3e0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2e3f0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2e400 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2e410 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2e420 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2e430 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2e440 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2e450 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2e460 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2e470 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2e480 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2e490 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2e4a0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2e4b0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2e4c0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2e4d0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2e4e0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2e4f0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2e500 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2e510 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2e520 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e530 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2e540 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2e550 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2e560 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2e570 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2e580 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2e590 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2e5a0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2e5b0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2e5c0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2e5d0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2e5e0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2e5f0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2e600 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2e610 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2e620 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2e630 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2e640 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2e650 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2e660 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2e670 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2e680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2e690 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2e6a0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2e6b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2e6c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2e6d0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2e6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2e6f0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2e700 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2e710 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2e720 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2e730 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2e740 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2e750 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2e760 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2e770 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2e780 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2e790 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2e7a0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2e7b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2e7c0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2e7d0 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2e7e0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2e7f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2e800 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2e810 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e830 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2e840 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2e850 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2e860 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2e870 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2e890 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2e8a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2e8b0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2e8c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e8d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2e8e0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2e8f0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2e900 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2e910 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2e920 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2e930 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2e940 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2e950 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2e960 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2e970 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2e980 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2e990 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2e9a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2e9b0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2e9c0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2e9d0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2e9e0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2e9f0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2ea00 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2ea10 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2ea20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2ea30 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2ea40 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2ea50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2ea60 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2ea70 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2ea80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2ea90 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2eaa0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2eab0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2eac0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2ead0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2eae0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2eaf0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2eb00 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2eb10 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2eb20 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2eb30 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2eb40 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2eb50 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2eb60 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2eb70 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2eb80 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2eb90 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2eba0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2ebb0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2ebc0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2ebd0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2ebe0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ebf0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2ec00 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2ec10 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2ec20 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2ec30 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2ec40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ec50 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2ec60 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2ec70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ec80 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2ec90 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2eca0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2ecb0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2ecc0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2ecd0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2ece0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2ecf0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2ed00 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2ed10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ed20 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2ed30 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2ed40 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2ed50 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2ed60 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2ed70 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2ed80 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2ed90 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2eda0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2edb0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2edc0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2edd0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2ede0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2edf0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2ee00 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2ee10 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2ee20 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2ee30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2ee40 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2ee50 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2ee60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2ee70 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2ee80 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2ee90 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2eea0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2eeb0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2eec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2eed0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2eee0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2eef0 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2ef00 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2ef10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2ef20 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2ef30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2ef40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2ef50 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2ef60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2ef70 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2ef80 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2ef90 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2efa0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2efb0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2efc0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2efd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2efe0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2eff0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2f000 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2f010 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2f020 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2f030 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2f040 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2f050 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2f060 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2f070 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2f080 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2f090 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2f0a0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2f0b0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2f0c0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2f0d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2f0e0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2f0f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2f100 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2f110 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2f120 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2f130 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2f140 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2f150 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2f160 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2f170 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2f180 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2f190 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2f1a0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2f1b0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2f1c0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2f1d0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2f1e0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2f1f0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2f200 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2f210 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2f220 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f230 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2f240 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2f250 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2f260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f270 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2f280 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2f290 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2f2a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f2b0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2f2c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f2d0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2f2e0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2f2f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f300 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2f310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f320 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2f330 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2f340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f350 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2f360 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2f370 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2f380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2f390 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2f3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2f3b0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2f3c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2f3d0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2f3e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2f3f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f400 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2f410 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2f420 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2f430 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f440 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2f450 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f460 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2f470 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2f480 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2f490 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2f4a0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2f4b0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2f4c0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2f4d0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2f4e0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2f4f0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2f500 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2f510 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2f520 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2f530 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2f540 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2f550 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f560 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2f570 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2f580 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f590 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2f5a0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2f5b0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2f5c0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2f5d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2f5e0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2f5f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2f600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2f610 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2f630 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2f640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2f650 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2f660 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f670 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2f680 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2f690 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2f6a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f6b0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2f6c0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2f6d0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2f6e0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2f6f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f700 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2f710 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2f720 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2f730 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2f740 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2f750 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2f760 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2f770 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2f780 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2f790 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f7a0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2f7b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2f7c0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2f7d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f7e0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2f7f0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2f800 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2f810 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2f820 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2f830 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2f840 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2f850 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2f860 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2f870 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2f880 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2f890 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2f8a0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2f8b0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2f8c0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2f8d0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2f8e0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2f8f0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2f900 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2f910 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2f920 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2f930 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2f940 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2f950 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2f960 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2f970 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2f980 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2f990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f9a0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2f9b0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2f9c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f9d0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2f9e0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2f9f0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2fa00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2fa10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2fa20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2fa30 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2fa40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2fa50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2fa60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2fa70 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2fa80 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2fa90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2faa0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2fab0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2fac0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2fad0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2fae0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2faf0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2fb00 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2fb10 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2fb20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2fb30 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2fb40 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2fb50 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2fb60 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2fb70 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2fb80 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2fb90 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2fba0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2fbb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fbc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2fbd0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2fbe0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2fbf0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2fc00 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2fc10 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2fc20 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2fc30 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2fc40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2fc50 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2fc60 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2fc70 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2fc80 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2fc90 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2fca0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2fcb0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2fcc0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2fcd0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2fce0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fcf0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2fd00 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2fd10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2fd20 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2fd30 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2fd40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2fd50 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2fd60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2fd70 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2fd80 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2fd90 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2fda0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2fdb0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2fdc0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2fdd0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2fde0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2fdf0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2fe00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2fe10 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2fe20 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2fe30 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2fe40 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2fe50 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2fe60 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2fe70 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2fe80 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2fe90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2fea0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2feb0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2fec0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2fed0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2fee0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2fef0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2ff00 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ff10 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2ff20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2ff30 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2ff40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ff50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2ff60 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2ff70 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2ff80 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2ff90 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2ffa0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2ffb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2ffc0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2ffd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2ffe0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2fff0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
30000 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30010 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
30020 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
30030 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
30040 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
30050 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
30060 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
30070 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
30080 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
30090 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
300a0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
300b0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
300c0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
300d0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
300e0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
300f0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
30100 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
30110 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
30120 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
30130 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
30140 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
30150 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
30160 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
30170 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
30180 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30190 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
301a0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
301b0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
301c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
301d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
301e0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
301f0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
30200 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
30210 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
30220 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
30230 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
30240 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
30250 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
30260 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
30270 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
30280 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
30290 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
302a0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
302b0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
302c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
302d0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
302e0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
302f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
30300 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
30310 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
30320 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30330 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
30340 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
30350 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
30360 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
30370 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
30380 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
30390 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
303a0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
303b0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
303c0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
303d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
303e0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
303f0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
30400 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
30410 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
30420 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
30430 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
30440 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
30450 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
30460 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
30470 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
30480 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
30490 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
304a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
304b0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
304c0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
304d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
304e0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
304f0 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
30500 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
30510 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
30520 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
30530 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
30540 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
30550 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
30560 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
30570 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30580 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
30590 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
305a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
305b0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
305c0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
305d0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
305e0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
305f0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
30600 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
30610 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
30620 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
30630 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
30640 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
30650 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
30660 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
30670 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
30680 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
30690 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
306a0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
306b0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
306c0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
306d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
306e0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
306f0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
30700 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
30710 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
30720 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
30730 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
30740 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
30750 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
30760 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
30770 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
30780 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
30790 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
307a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
307b0 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
307c0 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
307d0 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
307e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
307f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
30800 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
30810 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
30820 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
30830 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
30840 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
30850 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
30860 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
30870 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
30880 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
30890 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
308a0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
308b0 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
308c0 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
308d0 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
308e0 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
308f0 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
30900 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
30910 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
30920 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
30930 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
30940 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
30950 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
30960 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
30970 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
30980 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
30990 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
309a0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
309b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
309c0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
309d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
309e0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
309f0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
30a00 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
30a10 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
30a20 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
30a30 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
30a40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
30a50 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
30a60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
30a70 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
30a80 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
30a90 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
30aa0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
30ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30ac0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
30ad0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
30ae0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
30af0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
30b00 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
30b10 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
30b20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
30b30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
30b40 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
30b50 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
30b60 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
30b70 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
30b80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30b90 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
30ba0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
30bb0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
30bc0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
30bd0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
30be0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
30bf0 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
30c00 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30c10 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
30c20 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
30c30 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
30c40 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
30c50 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
30c60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
30c70 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
30c80 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
30c90 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
30ca0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
30cb0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
30cc0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
30cd0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
30ce0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
30cf0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
30d00 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
30d10 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30d20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30d30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
30d40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30d50 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
30d60 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
30d70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30d80 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
30d90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30da0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30db0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30dc0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
30dd0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
30de0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
30df0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30e00 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
30e10 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
30e20 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
30e30 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
30e40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
30e60 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30e70 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
30e80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30e90 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
30ea0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
30eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30ec0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
30ed0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
30ee0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
30ef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
30f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30f10 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
30f20 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
30f30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
30f40 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
30f50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30f60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30f70 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30f80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30f90 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30fa0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30fb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
30fc0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
30fd0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30fe0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
30ff0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
31000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31010 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
31020 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
31030 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
31040 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
31050 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31060 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
31070 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31080 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
31090 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
310a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
310b0 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
310c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
310d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
310e0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
310f0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
31100 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
31110 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
31120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31130 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
31140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31150 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
31160 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
31170 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31180 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
31190 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
311a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
311b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
311c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
311d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
311e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
311f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
31200 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
31210 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
31220 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
31230 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
31240 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
31250 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
31260 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
31270 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
31280 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
31290 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
312a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
312b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
312c0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
312d0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
312e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
312f0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
31300 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
31310 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
31320 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
31330 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
31340 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
31350 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
31360 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
31370 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
31380 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
31390 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
313a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
313b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
313c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
313d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
313e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
313f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
31400 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
31410 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31420 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
31430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
31440 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
31450 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
31460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31470 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
31480 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
31490 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
314a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
314b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
314c0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
314d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
314e0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
314f0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
31500 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
31510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31520 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
31530 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
31540 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
31550 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
31560 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
31570 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
31580 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
31590 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
315a0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
315b0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
315c0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
315d0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
315e0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
315f0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
31600 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
31610 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
31620 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
31630 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
31640 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
31650 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
31660 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
31670 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
31680 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
31690 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
316a0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
316b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
316c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
316d0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
316e0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
316f0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
31700 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
31710 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
31720 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
31730 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
31740 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
31750 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31760 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
31770 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
31780 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
31790 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
317a0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
317b0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
317c0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
317d0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
317e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
317f0 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
31800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31810 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
31820 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
31830 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
31840 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
31850 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31860 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
31870 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31880 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31890 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
318a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
318b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
318c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
318d0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
318e0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
318f0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
31900 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
31910 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
31920 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31930 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
31940 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
31950 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
31960 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
31970 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
31980 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
31990 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
319a0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
319b0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
319c0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
319d0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
319e0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
319f0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
31a00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
31a10 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
31a20 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
31a30 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
31a40 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
31a50 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
31a60 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
31a70 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
31a80 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
31a90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31aa0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
31ab0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
31ac0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
31ad0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
31ae0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
31af0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
31b00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31b10 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
31b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
31b30 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
31b40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
31b50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31b60 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
31b70 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
31b80 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
31b90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
31ba0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
31bb0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
31bc0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
31bd0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31be0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
31bf0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
31c00 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
31c10 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
31c20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
31c30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
31c40 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
31c50 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
31c60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
31c70 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
31c80 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
31c90 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
31ca0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
31cb0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
31cc0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
31cd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31ce0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
31cf0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
31d00 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
31d10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31d20 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
31d30 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
31d40 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
31d50 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
31d60 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
31d70 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
31d80 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
31d90 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
31da0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
31db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31dc0 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
31dd0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
31de0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
31df0 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
31e00 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
31e10 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
31e20 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
31e30 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
31e40 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
31e50 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
31e60 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
31e70 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
31e80 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
31e90 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
31ea0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
31eb0 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
31ec0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
31ed0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
31ee0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
31ef0 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
31f00 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
31f10 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
31f20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
31f30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
31f40 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
31f50 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
31f60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31f70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31f80 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
31f90 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31fa0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31fb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31fc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31fd0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31fe0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
31ff0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
32000 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
32010 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
32020 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
32030 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
32040 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
32050 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32060 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
32070 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
32080 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
32090 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
320a0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
320b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
320c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
320d0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
320e0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
320f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32100 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32110 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
32120 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
32130 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
32140 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
32150 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
32160 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
32170 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
32180 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
32190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
321a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
321b0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
321c0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
321d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
321e0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
321f0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
32200 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
32210 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
32220 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
32230 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
32240 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
32250 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
32260 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
32270 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
32280 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
32290 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
322a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
322b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
322c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
322d0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
322e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
322f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
32300 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
32310 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
32320 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
32330 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
32340 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
32350 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
32360 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
32370 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32380 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
32390 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
323a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
323b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
323c0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
323d0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
323e0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
323f0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
32400 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
32410 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
32420 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
32430 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
32440 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
32450 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
32460 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
32470 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
32480 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32490 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
324a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
324b0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
324c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
324d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
324e0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
324f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32500 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
32510 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
32520 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32530 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32540 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
32550 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
32560 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
32570 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32580 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
32590 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
325a0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
325b0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
325c0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
325d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
325e0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
325f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
32600 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
32610 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
32620 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
32630 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
32640 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
32650 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
32660 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
32670 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
32680 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
32690 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
326a0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
326b0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
326c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
326d0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
326e0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
326f0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
32700 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
32710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
32720 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
32730 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
32740 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
32750 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
32760 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
32770 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
32780 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
32790 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
327a0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
327b0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
327c0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
327d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
327e0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
327f0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
32800 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
32810 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
32820 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
32830 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
32840 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
32850 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32860 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
32870 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
32880 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
32890 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
328a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
328b0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
328c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
328d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
328e0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
328f0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
32900 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
32910 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
32920 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
32930 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
32940 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
32950 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
32960 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
32970 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
32980 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
32990 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
329a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
329b0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
329c0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
329d0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
329e0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
329f0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
32a00 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
32a10 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
32a20 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
32a30 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
32a40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
32a50 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
32a60 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
32a70 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
32a80 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
32a90 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
32aa0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
32ab0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
32ac0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
32ad0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
32ae0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
32af0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
32b00 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
32b10 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
32b20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
32b30 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
32b40 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
32b50 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
32b60 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
32b70 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
32b80 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
32b90 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
32ba0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
32bb0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
32bc0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
32bd0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
32be0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
32bf0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
32c00 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
32c10 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
32c20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32c30 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
32c40 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
32c50 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
32c60 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
32c70 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
32c80 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
32c90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
32ca0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
32cb0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
32cc0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
32cd0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
32ce0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
32cf0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
32d00 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
32d10 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
32d20 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
32d30 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
32d40 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
32d50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32d60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
32d70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
32d80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
32d90 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
32da0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32db0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32dc0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32dd0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
32de0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
32df0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32e00 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
32e10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
32e20 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
32e30 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32e40 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
32e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32e60 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
32e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
32e80 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
32e90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32ea0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32eb0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
32ec0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
32ed0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
32ee0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
32ef0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
32f00 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
32f10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32f20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
32f30 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32f40 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
32f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32f60 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
32f70 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
32f80 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
32f90 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
32fa0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
32fb0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
32fc0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
32fd0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
32fe0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
32ff0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
33000 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
33010 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
33020 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
33030 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
33040 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
33050 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
33060 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
33070 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
33080 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
33090 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
330a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
330b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
330c0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
330d0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
330e0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
330f0 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
33100 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
33110 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
33120 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
33130 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
33140 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
33150 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
33160 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
33170 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
33180 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
33190 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
331a0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
331b0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
331c0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
331d0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
331e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
331f0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
33200 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
33210 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
33220 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
33230 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
33240 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
33250 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
33260 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
33270 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
33280 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
33290 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
332a0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
332b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
332c0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
332d0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
332e0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
332f0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
33300 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
33310 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
33320 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
33330 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
33340 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
33350 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
33360 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
33370 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
33380 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
33390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
333a0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
333b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
333c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
333d0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
333e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
333f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33400 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
33410 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
33420 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33430 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
33440 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
33450 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
33460 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
33470 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
33480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
334a0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
334b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
334c0 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
334d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
334e0 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
334f0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
33500 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
33510 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
33520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33530 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
33540 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
33550 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
33560 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
33570 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
33580 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
33590 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
335a0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
335b0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
335c0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
335d0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
335e0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
335f0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
33600 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
33610 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
33620 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
33630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33640 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
33650 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
33660 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
33670 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
33680 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
33690 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
336a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
336b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
336c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
336d0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
336e0 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
336f0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
33700 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
33710 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
33720 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
33730 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
33740 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
33750 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
33760 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
33770 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
33780 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
33790 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
337a0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
337b0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
337c0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
337d0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
337e0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
337f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
33800 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
33810 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
33820 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
33830 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
33840 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
33850 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
33860 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
33870 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
33880 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
33890 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
338a0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
338b0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
338c0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
338d0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
338e0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
338f0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
33900 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
33910 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
33920 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
33930 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
33940 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
33950 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33960 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
33970 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
33980 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
33990 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
339a0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
339b0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
339c0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
339d0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
339e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
339f0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
33a00 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
33a10 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
33a20 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
33a30 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
33a40 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
33a50 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
33a60 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
33a70 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
33a80 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
33a90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33aa0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
33ab0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
33ac0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33ad0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
33ae0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
33af0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
33b00 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
33b10 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
33b20 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
33b30 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
33b40 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
33b50 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
33b60 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
33b70 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
33b80 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
33b90 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
33ba0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
33bb0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
33bc0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
33bd0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
33be0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
33bf0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
33c00 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
33c10 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
33c20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
33c30 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
33c40 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
33c50 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
33c60 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
33c70 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
33c80 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
33c90 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
33ca0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
33cb0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
33cc0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
33cd0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
33ce0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
33cf0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
33d00 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
33d10 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
33d20 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
33d30 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
33d40 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
33d50 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
33d60 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
33d70 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
33d80 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
33d90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
33da0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
33db0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
33dc0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
33dd0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
33de0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
33df0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
33e00 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
33e10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
33e20 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
33e30 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
33e40 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
33e50 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
33e60 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
33e70 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
33e80 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
33e90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33ea0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
33eb0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
33ec0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
33ed0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
33ee0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
33ef0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
33f00 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
33f10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
33f20 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
33f30 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
33f40 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
33f50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33f60 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
33f70 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
33f80 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
33f90 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
33fa0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
33fb0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
33fc0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
33fd0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
33fe0 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
33ff0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34000 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
34010 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
34020 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
34030 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
34040 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
34050 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
34060 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
34070 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
34080 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
34090 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
340a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
340b0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
340c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
340d0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
340e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
340f0 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
34100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
34110 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
34120 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
34130 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
34140 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
34150 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
34160 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
34170 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
34180 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
34190 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
341a0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
341b0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
341c0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
341d0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
341e0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
341f0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
34200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
34210 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
34220 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
34230 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
34240 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
34250 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
34260 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
34270 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
34280 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
34290 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
342a0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
342b0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
342c0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
342d0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
342e0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
342f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
34300 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
34310 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
34320 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
34330 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
34340 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
34350 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
34360 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
34370 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
34380 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
34390 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
343a0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
343b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
343c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
343d0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
343e0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
343f0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
34400 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
34410 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
34420 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
34430 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
34440 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
34450 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
34460 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
34470 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
34480 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
34490 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
344a0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
344b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
344c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
344d0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
344e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
344f0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
34500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
34510 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
34520 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
34530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34540 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34550 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
34560 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
34570 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
34580 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
34590 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
345a0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
345b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
345c0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
345d0 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
345e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
345f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
34600 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
34610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34620 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
34630 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
34640 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
34650 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
34660 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34670 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
34680 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34690 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
346a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
346b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
346c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
346d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
346e0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
346f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34700 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
34710 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
34720 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
34730 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
34740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
34750 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
34760 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
34770 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
34780 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
34790 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
347a0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
347b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
347c0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
347d0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
347e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
347f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34800 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
34810 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
34820 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
34830 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
34840 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
34850 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
34860 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
34870 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
34880 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
34890 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
348a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
348b0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
348c0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
348d0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
348e0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
348f0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
34900 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
34910 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
34920 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
34930 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
34940 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
34950 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
34960 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
34970 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
34980 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
34990 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
349a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
349b0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
349c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
349d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
349e0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
349f0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
34a00 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
34a10 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
34a20 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
34a30 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
34a40 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
34a50 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
34a60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
34a70 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
34a80 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
34a90 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
34aa0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
34ab0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
34ac0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
34ad0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
34ae0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
34af0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
34b00 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
34b10 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
34b20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
34b30 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
34b40 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
34b50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
34b60 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
34b70 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
34b80 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
34b90 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
34ba0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
34bb0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
34bc0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
34bd0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
34be0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
34bf0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
34c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34c10 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
34c20 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
34c30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
34c40 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
34c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
34c60 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
34c70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
34c80 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
34c90 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
34ca0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
34cb0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
34cc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
34cd0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
34ce0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
34cf0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
34d00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
34d10 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
34d20 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
34d30 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34d40 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
34d50 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
34d60 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
34d70 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
34d80 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
34d90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34da0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
34db0 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
34dc0 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
34dd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
34df0 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
34e00 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
34e10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
34e30 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
34e40 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
34e50 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
34e60 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34e70 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
34e80 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
34e90 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
34ea0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34eb0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34ec0 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
34ed0 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
34ee0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34ef0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34f00 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
34f10 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
34f20 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
34f30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
34f50 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
34f60 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
34f70 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
34f80 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
34f90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34fa0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
34fb0 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
34fc0 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34fd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34ff0 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
35000 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
35010 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
35020 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
35030 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
35040 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
35050 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
35060 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
35070 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
35080 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
35090 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
350a0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
350b0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
350c0 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
350d0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
350e0 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
350f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
35100 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
35110 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
35120 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
35130 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
35140 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
35150 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
35160 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
35170 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
35180 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
35190 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
351a0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
351b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
351c0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
351d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
351e0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
351f0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
35200 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
35210 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
35220 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
35230 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35240 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
35250 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
35260 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
35270 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
35280 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
35290 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
352a0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
352b0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
352c0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
352d0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
352e0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
352f0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
35300 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
35310 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
35320 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
35330 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
35340 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
35350 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
35360 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
35370 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
35380 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
35390 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
353a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
353b0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
353c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
353d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
353e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
353f0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
35400 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
35410 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
35420 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
35430 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
35440 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
35450 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
35460 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
35470 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35480 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
35490 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
354a0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
354b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
354c0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
354d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
354e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
354f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
35500 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
35510 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
35520 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
35530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
35540 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
35550 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
35560 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
35570 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
35580 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35590 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
355a0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
355b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
355c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
355d0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
355e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
355f0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
35600 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35610 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
35620 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
35630 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
35640 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
35650 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
35660 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
35670 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
35680 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
35690 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
356a0 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
356b0 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
356c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
356d0 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
356e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
356f0 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
35700 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
35710 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
35720 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
35730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35740 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
35750 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
35760 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
35770 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
35780 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
35790 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
357a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
357b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
357c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
357d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
357e0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
357f0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
35800 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
35810 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
35820 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
35830 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
35840 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35850 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
35860 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
35870 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
35880 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
35890 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
358a0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
358b0 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
358c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
358d0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
358e0 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
358f0 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
35900 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
35910 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
35920 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
35930 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
35940 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
35950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
35960 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
35970 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
35980 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
35990 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
359a0 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
359b0 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
359c0 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
359d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
359e0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
359f0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
35a00 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
35a10 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
35a20 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
35a30 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
35a40 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
35a50 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
35a60 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
35a70 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
35a80 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
35a90 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
35aa0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
35ab0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
35ac0 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
35ad0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
35ae0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
35af0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
35b00 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
35b10 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
35b20 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
35b30 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
35b40 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
35b50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
35b60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
35b70 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
35b80 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
35b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35ba0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
35bb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35bc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35bd0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
35be0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
35bf0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
35c00 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
35c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35c20 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
35c30 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
35c40 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
35c50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
35c60 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
35c70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35c80 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
35c90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35ca0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
35cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
35cc0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
35cd0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
35ce0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
35cf0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
35d00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35d10 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
35d20 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
35d30 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
35d40 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35d50 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
35d60 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
35d70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35d80 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
35d90 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
35da0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35db0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
35dc0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
35dd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35de0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
35df0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35e00 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35e10 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
35e20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35e30 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
35e40 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
35e50 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
35e60 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
35e70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35e80 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
35e90 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
35ea0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
35eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35ec0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
35ed0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
35ee0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
35ef0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
35f00 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
35f10 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
35f20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
35f30 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
35f40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35f50 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
35f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35f70 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
35f80 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
35f90 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
35fa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35fb0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35fc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
35fd0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35fe0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
35ff0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
36000 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
36010 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
36020 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
36030 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
36040 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
36050 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36060 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36070 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36080 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
36090 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
360a0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
360b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
360c0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
360d0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
360e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
360f0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
36100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36110 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
36120 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
36130 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
36140 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
36150 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
36160 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
36170 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
36180 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
36190 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
361a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
361b0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
361c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
361d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
361e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
361f0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
36200 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36210 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
36220 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
36230 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
36240 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
36250 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
36260 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
36270 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
36280 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
36290 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
362a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
362b0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
362c0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
362d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
362e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
362f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
36300 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
36310 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
36320 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
36330 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
36340 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36350 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
36360 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36370 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
36380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36390 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
363a0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
363b0 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
363c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
363d0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
363e0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
363f0 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
36400 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
36410 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
36420 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
36430 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36440 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
36450 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
36460 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
36470 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
36480 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
36490 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
364a0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
364b0 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
364c0 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
364d0 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
364e0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
364f0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
36500 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
36510 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
36520 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
36530 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
36540 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
36550 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
36560 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
36570 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
36580 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
36590 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
365a0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
365b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
365c0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
365d0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
365e0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
365f0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
36600 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
36610 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
36620 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
36630 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
36640 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
36650 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
36660 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
36670 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
36680 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
36690 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
366a0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
366b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
366c0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
366d0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
366e0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
366f0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
36700 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
36710 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
36720 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
36730 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
36740 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
36750 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
36760 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
36770 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
36780 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
36790 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
367a0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
367b0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
367c0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
367d0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
367e0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
367f0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
36800 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
36810 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
36820 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
36830 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
36840 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
36850 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
36860 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
36870 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
36880 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
36890 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
368a0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
368b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
368c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
368d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
368e0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
368f0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
36900 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
36910 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
36920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
36930 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
36940 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
36950 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
36960 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
36970 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
36980 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
36990 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
369a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
369b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
369c0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
369d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
369e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
369f0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
36a00 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
36a10 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
36a20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
36a30 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
36a40 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
36a50 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
36a60 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
36a70 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
36a80 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
36a90 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
36aa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
36ab0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
36ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36ad0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
36ae0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
36af0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
36b00 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
36b10 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
36b20 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
36b30 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
36b40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
36b50 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
36b60 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
36b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36b80 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
36b90 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
36ba0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
36bb0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
36bc0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
36bd0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
36be0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
36bf0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
36c00 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
36c10 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
36c20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
36c30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36c40 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
36c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36c60 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
36c70 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
36c80 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
36c90 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
36ca0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
36cb0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
36cc0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
36cd0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
36ce0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
36cf0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
36d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
36d10 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
36d20 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
36d30 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
36d40 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
36d50 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
36d60 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
36d70 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
36d80 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
36d90 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
36da0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
36db0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
36dc0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
36dd0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
36de0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36df0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
36e00 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
36e10 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
36e20 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
36e30 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
36e40 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
36e50 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
36e60 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
36e70 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
36e80 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
36e90 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
36ea0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
36eb0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
36ec0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
36ed0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
36ee0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
36ef0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
36f00 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
36f10 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
36f20 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
36f30 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
36f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36f50 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36f70 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36f80 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
36f90 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
36fa0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36fb0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
36fc0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36fd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36fe0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
36ff0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37000 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
37010 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
37020 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
37030 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
37040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
37050 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
37060 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
37070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37080 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
37090 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
370a0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
370b0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
370c0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
370d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
370e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
370f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
37100 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
37110 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
37120 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
37130 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
37140 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
37150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
37160 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
37170 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
37180 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
37190 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
371a0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
371b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
371c0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
371d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
371e0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
371f0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
37200 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
37210 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
37220 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
37230 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
37240 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
37250 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
37260 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
37270 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
37280 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
37290 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
372a0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
372b0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
372c0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
372d0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
372e0 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
372f0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
37300 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
37310 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
37320 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
37330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37340 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
37350 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
37360 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  ]..**.** As long
37370 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 70 61   as the input pa
37380 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 6f 72  rameters are cor
37390 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f 75 74  rect, these rout
373a0 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a  ines will only.*
373b0 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f 75 74  * fail if an out
373c0 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72  -of-memory error
373d0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
373e0 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73 69   format conversi
373f0 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20  on..** Only the 
37400 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65 74  following subset
37410 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 61   of interfaces a
37420 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 6f 75  re subject to ou
37430 74 2d 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65  t-of-memory.** e
37440 72 72 6f 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rrors:.**.** <ul
37450 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
37460 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a  3_column_blob().
37470 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
37480 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a  column_text().**
37490 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
374a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
374b0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
374c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
374d0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
374e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
374f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ul>.**.** If 
37500 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  an out-of-memory
37510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 74   error occurs, t
37520 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
37530 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 73 65 0a  alue from these.
37540 2a 2a 20 72 6f 75 74 69 6e 65 73 20 69 73 20 74  ** routines is t
37550 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 68  he same as if th
37560 65 20 63 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e  e column had con
37570 74 61 69 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55  tained an SQL NU
37580 4c 4c 20 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c  LL value..** Val
37590 69 64 20 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75  id SQL NULL retu
375a0 72 6e 73 20 63 61 6e 20 62 65 20 64 69 73 74 69  rns can be disti
375b0 6e 67 75 69 73 68 65 64 20 66 72 6f 6d 20 6f 75  nguished from ou
375c0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
375d0 72 73 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e  rs.** by invokin
375e0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  g the [sqlite3_e
375f0 72 72 63 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69  rrcode()] immedi
37600 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65 20  ately after the 
37610 73 75 73 70 65 63 74 0a 2a 2a 20 72 65 74 75 72  suspect.** retur
37620 6e 20 76 61 6c 75 65 20 69 73 20 6f 62 74 61 69  n value is obtai
37630 6e 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ned and before a
37640 6e 79 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ny.** other SQLi
37650 74 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  te interface is 
37660 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 73 61  called on the sa
37670 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37680 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e  nection]..*/.con
37690 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
376a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
376b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
376c0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
376d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
376e0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
376f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
37700 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
37710 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
37720 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
37730 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
37740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
37750 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
37760 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
37770 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
37780 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
37790 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
377a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
377b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
377c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
377d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
377e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
377f0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
37800 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
37810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
37820 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
37830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37840 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
37850 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
37860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37870 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
37880 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
37890 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
378a0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
378b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
378c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
378d0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
378e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
378f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
37900 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
37910 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
37920 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
37930 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
37940 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
37950 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37960 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
37970 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
37980 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
37990 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
379a0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
379b0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
379c0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
379d0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
379e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
379f0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
37a00 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
37a10 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
37a20 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
37a30 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
37a40 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
37a50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
37a60 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
37a70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
37a80 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
37a90 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
37aa0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
37ab0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
37ac0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
37ad0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
37ae0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
37af0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
37b00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37b10 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
37b20 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
37b30 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
37b40 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
37b50 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
37b60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
37b70 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
37b80 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
37b90 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
37ba0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
37bb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
37bc0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
37bd0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
37be0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
37bf0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
37c00 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
37c10 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
37c20 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
37c30 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
37c40 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
37c50 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
37c60 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
37c70 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
37c80 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
37c90 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
37ca0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
37cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
37cc0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
37cd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37ce0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
37cf0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
37d00 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
37d10 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
37d20 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
37d30 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
37d40 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
37d50 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
37d60 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
37d70 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
37d80 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
37d90 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
37da0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
37db0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
37dc0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
37dd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
37de0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
37df0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
37e00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
37e10 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
37e20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
37e30 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
37e40 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
37e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37e60 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
37e70 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
37e80 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
37e90 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
37ea0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
37eb0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
37ec0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
37ed0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
37ee0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
37ef0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
37f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
37f10 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
37f20 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
37f30 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
37f40 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
37f50 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
37f60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
37f70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37f80 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
37f90 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
37fa0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
37fb0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
37fc0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
37fd0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
37fe0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
37ff0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38000 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
38010 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
38020 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
38030 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
38040 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
38050 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
38060 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
38070 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
38080 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
38090 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
380a0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
380b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
380c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
380d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
380e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
380f0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
38100 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38110 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
38120 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
38130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
38140 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
38150 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
38160 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
38170 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
38180 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
38190 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
381a0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
381b0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
381c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
381d0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
381e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
381f0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
38200 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
38210 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
38220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38230 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
38240 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
38250 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
38260 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
38270 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
38280 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
38290 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
382a0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
382b0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
382c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
382d0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
382e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
382f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
38300 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
38310 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
38320 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
38330 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
38340 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
38350 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
38360 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
38370 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
38380 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
38390 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
383a0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
383b0 73 2e 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  s. The only diff
383c0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
383d0 2a 2a 20 74 68 65 20 74 68 72 65 65 20 22 73 71  ** the three "sq
383e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
383f0 63 74 69 6f 6e 2a 22 20 72 6f 75 74 69 6e 65 73  ction*" routines
38400 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
38410 63 6f 64 69 6e 67 20 0a 2a 2a 20 65 78 70 65 63  coding .** expec
38420 74 65 64 20 66 6f 72 20 74 68 65 20 73 65 63 6f  ted for the seco
38430 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
38440 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
38450 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 0a 2a 2a  nction being .**
38460 20 63 72 65 61 74 65 64 29 20 61 6e 64 20 74 68   created) and th
38470 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
38480 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
38490 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
384a0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
384b0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
384c0 65 72 2e 20 46 75 6e 63 74 69 6f 6e 20 73 71 6c  er. Function sql
384d0 69 74 65 33 5f 63 72 65 61 74 65 5f 77 69 6e 64  ite3_create_wind
384e0 6f 77 5f 66 75 6e 63 74 69 6f 6e 28 29 0a 2a 2a  ow_function().**
384f0 20 69 73 20 73 69 6d 69 6c 61 72 2c 20 62 75 74   is similar, but
38500 20 61 6c 6c 6f 77 73 20 74 68 65 20 75 73 65 72   allows the user
38510 20 74 6f 20 73 75 70 70 6c 79 20 74 68 65 20 65   to supply the e
38520 78 74 72 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  xtra callback fu
38530 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6e 65 65 64 65  nctions.** neede
38540 64 20 62 79 20 5b 61 67 67 72 65 67 61 74 65 20  d by [aggregate 
38550 77 69 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73  window functions
38560 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  ]..**.** ^The fi
38570 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
38580 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38590 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
385a0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
385b0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
385c0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
385d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
385e0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
385f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38600 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
38610 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
38620 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
38630 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
38640 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
38650 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
38660 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
38670 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
38680 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
38690 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
386a0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
386b0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
386c0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
386d0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
386e0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
386f0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
38700 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
38710 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
38720 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
38730 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
38740 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
38750 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
38760 2d 38 20 62 79 74 6