/ Hex Artifact Content
Login

Artifact 469aed42e75193b7f5d88d812befa961c04746869475f96fcf434c9f67079f66:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69  underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74  lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65  s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65  s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65  n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51  bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61  _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65  C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72   is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a  to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69   underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54   file handle.  T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74  his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61   pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74   and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c  he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ue there..**.** 
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  de.  .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53  opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a  QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20  iptor is placed 
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20  in "batch write 
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20  mode", which.** 
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71  means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65  tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a  ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74  ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54   the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53  TOMIC_WRITE].  S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64  ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61  o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65  tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a  LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73  * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45  uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72  MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c  ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43  osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b  C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20   make.** no VFS 
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20  interface calls 
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20  ite3_file] file 
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78  descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74  cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74  o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c  hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f  be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73  mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65   the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65  .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d  nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73  mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a  tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c  t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20  ol takes.** the 
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20  te mode so that 
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54  MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63  _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a  auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69  ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73  nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20  IC_WRITE] to be 
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  rolled back..** 
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72  ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c  ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74  e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20   of batch write 
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20  mode.** so that 
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e  are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51   never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  C_WRITE]..**.** 
ccc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ccd0: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d  TL_LOCK_TIMEOUT]
cce0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ccf0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
cd00: 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  OUT] opcode caus
cd10: 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f  es attempts to o
cd20: 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20  btain.** a file 
cd30: 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78  lock using the x
cd40: 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b  Lock or xShmLock
cd50: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
cd60: 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66  VFS to wait.** f
cd70: 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69  or up to M milli
cd80: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66  seconds before f
cd90: 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20  ailing, where M 
cda0: 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a  is the single .*
cdb0: 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  * unsigned integ
cdc0: 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  er parameter..**
cdd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
cde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
cdf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ce10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
ce20: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
ce30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
ce40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
ce50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ce60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
ce70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
ce80: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
ce90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
cea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
ceb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
cec0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
ced0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
cee0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cef0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
cf10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
cf20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
cf30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
cf40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
cf50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
cf60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
cf70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
cfa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
cfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cfc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cff0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d000: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d020: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d030: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d050: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d060: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d080: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d090: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d0b0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d0c0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d0e0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d0f0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d110: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d120: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d140: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d150: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d180: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d1a0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d1b0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d1c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d1d0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d1e0: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d210: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d220: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d240: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d250: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d280: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d290: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d2b0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d2c0: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d2e0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d2f0: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d310: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d320: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d340: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d350: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d370: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d380: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d3a0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d3b0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
d3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d3d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
d3e0: 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70        34../* dep
d3f0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d410: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
d420: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d430: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
d440: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
d460: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
d480: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
d490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
d4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
d4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
d4c0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
d4d0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
d4e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
d4f0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
d500: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
d510: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
d520: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
d530: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
d540: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
d550: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
d560: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
d570: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
d580: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
d590: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
d5a0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
d5b0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
d5c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
d5d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d5e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
d5f0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
d600: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
d610: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
d620: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d630: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
d640: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
d650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d660: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
d670: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
d680: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
d690: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
d6a0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
d6b0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
d6c0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
d6d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
d6e0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
d6f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
d700: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
d710: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
d720: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
d730: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
d740: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
d750: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
d760: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
d770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d780: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d790: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d7a0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
d7c0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
d7d0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d7e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d7f0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
d800: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
d810: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
d820: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
d830: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
d840: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
d850: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
d860: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
d870: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
d880: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
d890: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
d8a0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
d8b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
d8c0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
d8d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
d8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69   VFS interface i
d8f0: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65  s sometimes exte
d900: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e  nded by adding n
d910: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a  ew methods onto.
d920: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63  ** the end.  Eac
d930: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65  h time such an e
d940: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c  xtension occurs,
d950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d960: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d  eld.** is increm
d970: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72  ented.  The iVer
d980: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74  sion value start
d990: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a  ed out as 1 in.*
d9a0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  * SQLite [versio
d9b0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74  n 3.5.0] on [dat
d9c0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e  eof:3.5.0], then
d9d0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a   increased to 2.
d9e0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b  ** with SQLite [
d9f0: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f  version 3.7.0] o
da00: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d  n [dateof:3.7.0]
da10: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65  , and then incre
da20: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74  ased.** to 3 wit
da30: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  h SQLite [versio
da40: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74  n 3.7.6] on [dat
da50: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64  eof:3.7.6].  Add
da60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
da70: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  * may be appende
da80: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  d to the sqlite3
da90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20  _vfs object and 
daa0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
dab0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61  ue.** may increa
dac0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75  se again in futu
dad0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
dae0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  QLite..** Note t
daf0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
db00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
db10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
db20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
db30: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  ansition from.**
db40: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
db50: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73   3.5.9] to [vers
db60: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64  ion 3.6.0] on [d
db70: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20  ateof:3.6.0].** 
db80: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
db90: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
dba0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ot modified..**.
dbb0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
dbc0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
dbd0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
dbe0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
dbf0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
dc00: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
dc10: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
dc20: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
dc30: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
dc40: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
dc50: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
dc60: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
dc70: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
dc80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
dc90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
dca0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dcb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
dcc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
dcd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
dce0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
dcf0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
dd00: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
dd10: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
dd20: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
dd30: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
dd40: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
dd50: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
dd60: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
dd70: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
dd80: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
dd90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
dda0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ddb0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ddc0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
ddd0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
dde0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ddf0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
de00: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
de10: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
de20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
de30: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
de40: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
de50: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
de60: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
de70: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
de80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
de90: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
dea0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
deb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
dec0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ded0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
dee0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
def0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
df00: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
df10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
df20: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
df30: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
df40: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
df50: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
df60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
df70: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
df90: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
dfa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
dfb0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
dfc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
dfd0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
dfe0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
dff0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e000: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e010: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e020: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e030: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e050: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e060: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e070: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e080: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e090: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
e0a0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e0c0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e0d0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e0e0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e0f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e100: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e110: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e120: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e130: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e140: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e150: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e160: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e170: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e180: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e190: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e1a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e1b0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e1c0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e1d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e1e0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e1f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e200: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e210: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e220: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e230: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e240: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e250: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e260: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e270: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e280: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e290: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e2a0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e2c0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
e2e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
e2f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
e300: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
e310: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
e320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e330: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
e340: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
e350: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
e360: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
e370: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
e380: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
e390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
e3a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
e3b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
e3c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
e3d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
e3e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
e3f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
e400: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
e410: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
e420: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
e430: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
e440: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
e450: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
e460: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
e470: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
e480: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
e490: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
e4a0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
e4b0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
e4c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e4d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e4e0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
e4f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e500: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
e510: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e520: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
e530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e540: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
e550: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e560: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
e570: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
e590: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
e5b0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e5d0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
e5e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
e5f0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
e600: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
e610: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
e620: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
e630: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
e640: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
e650: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
e660: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
e670: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
e680: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
e690: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
e6a0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
e6b0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
e6c0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
e6d0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
e6e0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
e6f0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
e700: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
e710: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
e720: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
e730: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
e740: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e760: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
e770: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
e780: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
e790: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
e7a0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
e7b0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
e7c0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
e7d0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
e7e0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
e7f0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
e800: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
e810: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
e820: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
e830: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e840: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e850: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
e860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
e880: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e890: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
e8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
e8b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e8c0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
e8d0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
e8e0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
e8f0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e920: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
e930: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
e940: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
e950: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
e960: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
e970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
e980: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e990: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e9a0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
e9b0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
e9c0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
e9d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e9e0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
e9f0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
ea00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
ea10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
ea20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ea30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
ea40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
ea50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
ea60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
ea70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
ea80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
ea90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
eaa0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
eab0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
eac0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ead0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
eae0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
eaf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
eb00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
eb10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
eb20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
eb30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
eb40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
eb50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
eb60: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
eb70: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
eb80: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
eb90: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
eba0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
ebb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
ebc0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
ebd0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
ebe0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
ebf0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
ec00: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
ec10: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
ec20: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
ec30: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
ec40: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
ec50: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
ec60: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
ec90: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
eca0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ecb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
ecc0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
ecd0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
ece0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
ecf0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
ed00: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
ed10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ed20: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
ed30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
ed40: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
ed50: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
ed60: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
ed70: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
ed80: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
ed90: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
eda0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
edb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
edc0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
edd0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
ede0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
edf0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
ee00: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
ee10: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
ee20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ee30: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
ee40: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
ee50: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
ee60: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
ee70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
ee80: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
ee90: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
eea0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
eeb0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
eec0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
eed0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
eee0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
eef0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
ef00: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
ef10: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
ef20: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
ef30: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
ef40: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
ef50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ef60: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
ef70: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
ef80: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
ef90: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
efa0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
efb0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
efc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
efd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
efe0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
eff0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f000: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f010: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f030: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f040: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f050: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f060: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f070: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f080: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f090: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f0a0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f0b0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f0c0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f0d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f0e0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f0f0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f100: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f110: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f120: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f130: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f140: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f150: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f160: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f170: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f180: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f190: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f1a0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f1b0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f1c0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f1d0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f1e0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f1f0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f200: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f210: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f220: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f230: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f240: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f250: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f260: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f270: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f280: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f290: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f2a0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f2b0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f2c0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f2d0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
f2e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
f2f0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f300: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
f310: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
f320: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
f330: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
f340: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
f350: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
f360: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
f370: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
f380: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f390: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
f3a0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f3b0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
f3c0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
f3d0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
f3e0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
f3f0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
f400: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
f410: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
f420: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f430: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
f440: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
f450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
f460: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
f470: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
f480: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
f490: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
f4a0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
f4b0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
f4c0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
f4d0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
f4e0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
f4f0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
f500: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
f510: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
f520: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
f530: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
f540: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
f550: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
f560: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
f570: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
f580: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
f590: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
f5a0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
f5b0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
f5c0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
f5d0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
f5e0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
f5f0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
f600: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
f610: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
f620: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
f630: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
f640: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
f650: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
f660: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
f670: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
f680: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
f690: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
f6a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
f6b0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
f6c0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
f6d0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
f6e0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
f6f0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
f700: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
f710: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
f720: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
f730: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
f740: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f750: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
f760: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
f770: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
f780: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
f790: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
f7a0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
f7b0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
f7c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f7d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
f7e0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
f7f0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f800: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
f810: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
f820: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
f830: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
f840: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
f850: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
f860: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
f870: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
f880: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
f890: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
f8a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
f8b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f8c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f8d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f8e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f8f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f900: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f910: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f930: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f940: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f950: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f960: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f970: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f980: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f990: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f9b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f9c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f9d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f9e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f9f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
fa00: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
fa10: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa40: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
fa50: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
fa60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa80: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
fa90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
faa0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
fab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fad0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
fae0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
faf0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
fb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fb10: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
fb20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
fb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
fb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
fb50: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
fb60: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
fb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
fb80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fb90: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
fba0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
fbb0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fbc0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
fbd0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
fbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
fbf0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
fc00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
fc10: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
fc20: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
fc30: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
fc50: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
fc60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
fc70: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
fc80: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
fc90: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
fca0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fcb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fcc0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
fcd0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
fce0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
fcf0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
fd00: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
fd10: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
fd20: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
fd30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
fd40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
fd50: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
fd60: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fd70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fd80: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
fd90: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
fda0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fdb0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
fdc0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
fdd0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
fde0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
fdf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fe00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
fe20: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
fe30: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
fe40: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
fe50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fe60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fe70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
fe80: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
fe90: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fea0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
feb0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fec0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fed0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fee0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
fef0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ff00: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ff10: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ff20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ff30: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
ff40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ff50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ff60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ff70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ff80: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ff90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ffa0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ffb0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ffc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ffd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ffe0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
fff0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10000 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10010 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10030 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
10040 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
10050 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
10060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10070 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
10080 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
10090 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
100b0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
100c0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
100d0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
100e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10100 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10110 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10120 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10130 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10140 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10150 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10160 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10170 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
10180 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
10190 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
101a0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
101b0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
101c0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
101d0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
101e0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
101f0 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10200 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10210 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10220 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10230 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10240 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10250 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10260 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10270 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10280 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10290 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
102a0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
102c0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
102d0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
102e0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
102f0 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10300 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10310 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10330 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10340 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10350 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10360 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10370 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10380 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
103a0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
103b0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
103c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
103e0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
103f0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10400 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10410 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10420 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10430 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10440 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10450 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10460 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10470 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10480 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10490 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
104a0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
104b0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
104c0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
104d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
104e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
104f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10500 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10510 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10520 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10530 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10540 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10550 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10560 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10570 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10580 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10590 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
105a0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
105b0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
105c0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
105d0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
105e0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
105f0 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10600 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10620 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10630 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10640 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10650 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10660 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10670 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10680 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
10690 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
106a0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
106b0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
106c0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
106d0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
106e0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
106f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10700 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10710 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10720 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10730 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10750 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10760 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10770 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10780 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10790 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
107a0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
107b0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
107c0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
107d0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
107e0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
107f0 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10800 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10810 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10820 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10830 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10850 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10860 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10870 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10880 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10890 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
108a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
108c0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
108d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
108e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10900 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10910 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10920 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10930 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10940 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10960 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10970 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10980 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
10990 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
109a0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
109b0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
109c0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
109d0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
109e0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
109f0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10a10 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10a30 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10a40 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10a50 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10a60 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10a70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10a80 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
10a90 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
10aa0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
10ab0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10ac0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10ad0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ae0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10af0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10b00 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10b10 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10b20 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10b30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10b40 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10b50 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10b60 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10b70 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10b80 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10b90 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10bb0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10bc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10bd0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10bf0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10c00 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10c20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c50 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10c60 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10c70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
10ca0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
10cb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10cc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
10ce0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
10cf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d00 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
10d10 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10d20 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
10d30 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10d50 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
10d60 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
10d80 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
10d90 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
10da0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
10db0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10dc0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10dd0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
10de0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
10df0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
10e00 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
10e10 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
10e20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10e40 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10e60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
10e70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
10e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10eb0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10ec0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10ed0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10ee0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ef0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10f00 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10f10 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10f20 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10f30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10f40 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10f50 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
10f60 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
10f70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
10f80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10f90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10fa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10fb0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10fc0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10fd0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10fe0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10ff0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11000 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11010 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11020 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11040 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
11050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
11060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
11070 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
11080 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
11090 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
110a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
110b0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
110c0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
110d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
110e0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
110f0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11100 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11110 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11130 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11140 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11150 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11160 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11170 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11190 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
111a0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
111b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
111c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
111e0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11210 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11220 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11250 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11270 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
11280 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
11290 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
112a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
112b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
112c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
112d0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
112e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
112f0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11300 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11310 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11320 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11330 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11340 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11350 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11360 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11370 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11390 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
113a0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
113b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
113c0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
113d0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
113e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11400 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11410 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11420 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11430 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11440 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11450 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11460 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11470 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11480 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11490 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
114a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
114b0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
114c0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
114d0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
114e0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
114f0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11500 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11520 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11530 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11540 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11550 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11560 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11570 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11580 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11590 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
115a0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
115b0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
115d0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
115e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
115f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11600 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11610 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11620 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11630 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11640 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11650 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11660 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11670 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11680 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
11690 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
116a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
116b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
116c0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
116d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
116e0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
116f0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11700 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11710 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11720 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11730 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11740 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11750 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11760 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11770 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11790 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
117a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
117b0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
117c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
117d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
117e0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
117f0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11830 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11850 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11860 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11870 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11880 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
11890 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118a0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
118b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
118c0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
118d0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
118f0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11910 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
11920 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11940 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11950 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11960 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
11970 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11980 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
11990 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
119a0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
119b0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
119d0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
119e0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
119f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
11a00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
11a10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
11a20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
11a30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
11a40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
11a50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
11a60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
11a70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
11a80 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
11a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11aa0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
11ab0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
11ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
11ad0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
11ae0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
11af0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
11b00 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
11b10 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
11b20 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
11b30 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
11b40 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
11b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11b60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
11b70 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11b80 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11b90 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11bc0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11bd0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11be0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11bf0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11c00 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11c10 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11c20 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11c30 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11c50 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11c60 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11c70 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
11c80 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
11c90 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11ca0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11cb0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
11cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11ce0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
11cf0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
11d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11d20 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11d30 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
11d40 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
11d50 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
11d60 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
11d70 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
11d90 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11da0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
11db0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
11dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11dd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
11de0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
11df0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
11e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11e10 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
11e20 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
11e30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
11e40 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
11e50 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
11e60 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
11e70 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
11e80 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
11e90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
11ea0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11eb0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
11ec0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11ed0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11ee0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11ef0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11f00 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
11f10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
11f20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
11f30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11f40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11f50 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
11f60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
11f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
11f90 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
11fa0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
11fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
11fc0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
11fd0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
11fe0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
12000 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
12010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
12020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
12030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
12040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12050 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
12060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
12070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
12090 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
120a0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
120b0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
120c0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
120d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
120e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
120f0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
12100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
12110 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12120 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12130 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
12140 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
12150 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
12160 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
12170 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
12180 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
12190 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
121a0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
121b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
121c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
121d0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
121e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
121f0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12200 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12220 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12230 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12240 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12250 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12260 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12270 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12280 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12290 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
122a0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
122b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
122c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
122d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
122e0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
122f0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12310 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12320 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12330 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12340 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12360 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12370 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12380 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12390 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
123a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
123b0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
123c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
123d0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
123e0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
123f0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
12400 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12410 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12420 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12430 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12450 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12460 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12470 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12480 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
12490 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
124a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
124b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
124c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
124d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
124e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
124f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12500 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12510 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12520 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12530 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12540 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12550 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12570 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12580 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
12590 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
125a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
125b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
125c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
125d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
125e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
125f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
12600 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12610 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12620 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12630 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
12640 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
12650 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
12660 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
12670 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
12680 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
12690 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
126a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
126b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
126c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
126d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
126e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
126f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
12700 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12710 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12720 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
12730 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
12740 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12750 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
12760 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
12770 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
12780 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
12790 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
127a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
127b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
127c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
127d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
127e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
127f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
12800 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
12810 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
12820 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
12830 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
12840 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
12850 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
12860 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
12870 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
12880 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
12890 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
128a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
128b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
128c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
128d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
128e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
128f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
12900 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
12910 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
12920 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
12930 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
12940 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
12950 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
12960 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
12970 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
12980 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
12990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
129b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
129c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
129d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
129e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
129f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
12a00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
12a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
12a20 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
12a30 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
12a40 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
12a60 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
12a70 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
12a80 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
12a90 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
12aa0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
12ab0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
12ac0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
12ad0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
12ae0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
12af0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
12b00 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
12b10 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
12b20 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
12b30 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
12b40 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
12b50 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
12b60 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
12b70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
12b80 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
12b90 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
12ba0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12bb0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12bc0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
12bd0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
12be0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12bf0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
12c00 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
12c10 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
12c20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
12c30 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
12c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
12c50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12c60 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
12c70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
12c80 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
12c90 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
12ca0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
12cb0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
12cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12cd0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
12ce0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
12cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12d00 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
12d10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12d20 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
12d30 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
12d40 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
12d50 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
12d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
12d70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
12d80 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
12d90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12da0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
12db0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
12dc0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
12dd0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
12de0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
12df0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
12e00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
12e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
12e20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
12e30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
12e40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
12e50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
12e60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
12e70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
12e80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
12e90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12eb0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ed0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12ee0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12ef0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12f00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12f10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12f20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12f30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12f40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12f50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
12f60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
12f70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12f90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
12fa0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12fb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12fc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12fd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12fe0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12ff0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
13000 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
13010 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
13020 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
13030 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
13040 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
13050 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13060 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13070 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
13080 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
13090 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
130a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
130b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
130c0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
130d0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
130e0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
130f0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13100 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13110 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13120 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13130 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13160 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13170 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13190 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
131a0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
131b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
131c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
131d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
131e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
131f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13220 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13230 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13250 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13260 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13270 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13280 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13290 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
132a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
132b0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
132c0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
132d0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
132e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
132f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13300 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
13310 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
13320 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
13330 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
13340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13350 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
13360 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13380 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
13390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
133a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
133b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
133c0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
133d0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
133e0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
133f0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13400 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13410 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
13420 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13430 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13440 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
13450 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
13460 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
13470 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
13480 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
13490 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
134a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
134b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
134c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
134d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
134e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
134f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13500 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13510 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13520 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13530 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
13540 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
13550 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
13560 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
13570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13580 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
13590 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
135a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
135c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
135d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
135e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13600 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13620 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13630 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13640 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13650 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13660 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13670 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13680 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
13690 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
136a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
136b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
136c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
136d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
136e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
136f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13700 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
13720 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
13730 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13750 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13760 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
13770 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
13780 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
13790 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
137a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
137b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
137c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
137d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
137e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
137f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
13800 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
13810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13820 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13830 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
138a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
138b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
138c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
138d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
138e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
138f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
13900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13910 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13920 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13930 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13950 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13970 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
13980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13990 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
139a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
139b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
139c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
139f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
13a00 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
13a10 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
13a20 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
13a30 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
13a40 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
13a50 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
13a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a70 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13a90 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
13aa0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
13ab0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
13ac0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
13ae0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13af0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
13b00 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
13b10 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
13b20 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
13b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
13b40 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
13b50 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
13b60 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
13b70 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
13b80 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
13b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ba0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
13bb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
13bc0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
13bd0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
13be0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
13bf0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
13c00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13c10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13c20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13c30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13c50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
13c60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
13c70 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
13c80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
13c90 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13cb0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
13cc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13cd0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13cf0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
13d00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13d30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13d40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
13d50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13d70 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13d80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13d90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13db0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13de0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13df0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
13e00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
13e20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
13e30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
13e40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
13e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13e60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13e70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
13e80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
13e90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
13ea0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
13eb0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13ec0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
13ed0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
13ee0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
13ef0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
13f00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
13f10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13f20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
13f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
13f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13f70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13fb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13fd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13fe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
13ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
14000 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
14010 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
14020 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
14030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14040 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
14050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14080 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14090 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
140a0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
140b0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
140c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140d0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
140e0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
140f0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14100 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14120 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  ALL_MALLOC]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14140 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  MALL_MALLOC</dt>
14150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14170 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  L_MALLOC option 
14180 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
14190 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65  ument of.** type
141a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
141b0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
141c0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72  which if true pr
141d0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f  ovides a hint to
141e0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20  .** SQLite that 
141f0 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20  it should avoid 
14200 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
14210 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73  ocations if poss
14220 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ible..** SQLite 
14230 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20  will run faster 
14240 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f  if it is free to
14250 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f   make large memo
14260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a  ry allocations,.
14270 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c  ** but some appl
14280 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72  ication might pr
14290 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77  efer to run slow
142a0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66  er in exchange f
142b0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  or.** guarantees
142c0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72   about memory fr
142d0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  agmentation that
142e0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66   are possible if
142f0 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61   large.** alloca
14300 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65  tions are avoide
14310 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  d.  This hint is
14320 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a   normally off..*
14330 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14350 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14370 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14380 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14390 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
143a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
143b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
143c0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
143d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
143e0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
143f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14400 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14410 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14420 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14430 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14450 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14460 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14470 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14480 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
14490 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
144a0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
144b0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
144c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
144d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
144e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
144f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14500 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14510 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14520 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14530 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
14540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
14550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14560 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
14570 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
14580 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
14590 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
145a0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
145b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
145c0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
145d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
145e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
145f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
14600 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
14610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14620 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
14630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14640 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
14650 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14660 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
14670 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  option is no lon
14680 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  ger used..** </d
14690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
146b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
146c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
146d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
146e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
146f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
14700 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
14710 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
14720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
14730 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
14740 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
14750 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
14760 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
14780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
14790 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
147a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
147b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
147c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
147d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
147e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
147f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14800 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
14810 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14820 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14830 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14840 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
14850 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
14860 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
14870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
14880 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
14890 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
148a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
148b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
148c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
148d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
148e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
148f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
14900 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
14910 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
14920 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
14930 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
14940 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14950 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14960 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
14970 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
14980 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
14990 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
149a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
149c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
149d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
149e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
149f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
14a00 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
14a10 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
14a20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
14a30 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
14a40 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
14a50 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
14a60 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
14a70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14a80 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
14a90 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
14aa0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
14ab0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
14ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
14ad0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
14ae0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
14af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
14b00 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
14b10 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
14b20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
14b30 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
14b40 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
14b50 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
14b70 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
14b80 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
14b90 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
14ba0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
14bb0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
14bc0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
14bd0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
14be0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
14bf0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
14c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14c10 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
14c20 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
14c30 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
14c40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
14c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14c60 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
14c70 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
14c80 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
14c90 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
14ca0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
14cb0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
14cc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
14cd0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
14ce0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
14cf0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
14d00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
14d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
14d20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
14d30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14d40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
14d50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
14d60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
14d70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
14d80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14d90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14dd0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
14de0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14df0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14e00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14e10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14e20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14e40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14e50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14e60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14e70 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14e80 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
14e90 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14ea0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
14eb0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
14ec0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
14ed0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14ee0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14f00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14f10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14f20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14f30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14f40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14f50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14f70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14f80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
14f90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
14fa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
14fb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
14fc0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14fd0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14fe0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14ff0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
15000 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15010 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
15020 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
15030 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
15040 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
15050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
15060 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
15070 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
15080 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
15090 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
150a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
150b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
150c0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
150d0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
150e0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
150f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
15100 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15110 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
15120 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
15130 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
15140 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15150 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
15160 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15170 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
15180 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15190 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
151a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
151b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
151c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
151d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
151e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
151f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
15200 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
15210 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
15220 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
15240 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
15250 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
15260 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15270 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
152a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
152c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
152d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
152e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
152f0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15310 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15320 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
15330 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
15340 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15350 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
15360 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
15370 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
15380 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
15390 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
153a0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
153b0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
153c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
153d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
153e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
153f0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
15400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
15410 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
15420 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
15430 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15440 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15450 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15460 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15470 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15480 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15490 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
154a0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
154b0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
154c0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
154d0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
154f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
15500 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
15510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15520 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15530 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15560 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15580 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15590 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
155a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
155b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
155c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
155d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
155e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
155f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
15620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
15630 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
15640 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
15650 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
15660 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
15670 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
15680 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15690 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
156a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
156b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
156c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
156d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
156e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
156f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
15700 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
15710 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
15720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
15730 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15740 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15750 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15760 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15770 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15790 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
157a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
157b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
157c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
157d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
157e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
157f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15810 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
15820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15830 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</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 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15870 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
15880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
158a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
158b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
158c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
158d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
158e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
158f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
15900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
15910 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
15920 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15940 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15950 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15960 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
15970 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
15980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15990 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
159a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
159b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
159c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
159d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
159e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
159f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
15a00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
15a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15a20 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
15a30 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
15a40 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
15a50 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
15a60 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
15a70 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15a80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
15a90 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
15aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15ad0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
15ae0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b20 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
15b30 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
15b40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15b50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15b60 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
15b70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
15b80 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
15b90 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
15ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15bb0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
15bc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
15bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
15be0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15bf0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
15c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15c10 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15c30 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
15c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15c60 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
15c70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15c80 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
15c90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15cb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15cc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
15cd0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
15ce0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15d00 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15d10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15d20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15d30 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15d40 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15d50 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15d80 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
15d90 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
15da0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15dc0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
15dd0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15de0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15df0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15e00 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15e10 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15e20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15e30 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15e50 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15e60 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15e70 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15e80 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
15ea0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
15eb0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15ec0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
15ed0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
15ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15ef0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15f00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15f10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15f20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15f30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15f40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15f50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15f60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15f70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15f80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
15f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15fa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15fb0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
15fc0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
15fd0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
15fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16000 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
16010 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
16030 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
16040 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
16050 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
16060 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
16070 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
16080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16090 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
160a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
160b0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
160c0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
160d0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
160e0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
160f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
16100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
16110 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
16120 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
16130 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
16140 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
16150 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
16160 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
16170 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
16180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
16190 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
161a0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
161b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
161c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
161d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
161e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
161f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
16210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16220 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
16230 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16240 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
16250 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16260 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
16270 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
16280 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
16290 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
162a0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
162b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
162c0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
162d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
162e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
162f0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
16300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
16310 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
16320 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
16330 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16350 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
16360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
16370 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
16380 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
16390 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
163a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
163b0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
163c0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
163d0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
163e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
163f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
16400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
16410 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16420 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
16430 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
16440 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
16450 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
16460 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
16480 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16490 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
164a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
164b0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
164c0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
164e0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
164f0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
16500 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
16510 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
16520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
16530 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
16540 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16560 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16580 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16590 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
165a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
165b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
165c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
165d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
165e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
165f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
16600 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
16610 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
16620 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16630 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16660 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
16670 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
16680 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16690 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
166a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
166b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
166c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
166d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
166e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
166f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
16700 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
16710 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
16720 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
16730 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
16740 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
16750 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
16760 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
16770 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
16780 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
16790 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
167a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
167b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
167c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
167d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
167e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
167f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
16800 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
16810 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
16820 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
16830 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
16840 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
16850 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
16860 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
16870 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
16890 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
168a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
168b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
168c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
168e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
168f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
16900 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
16910 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
16920 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
16930 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
16940 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
16950 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
16960 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
16970 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
16980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16990 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
169a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
169b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
169c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
169d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
169e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
169f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
16a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
16a10 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
16a20 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
16a30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16a40 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
16a50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16a60 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
16a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
16a80 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
16a90 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
16aa0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
16ab0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
16ac0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
16ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
16ae0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
16af0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
16b00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
16b10 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
16b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
16b30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16b40 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
16b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16b60 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16b80 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
16b90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16ba0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
16bb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
16bc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
16bd0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
16be0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
16bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16c00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
16c10 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
16c20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16c30 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
16c40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
16c50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
16c60 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
16c70 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
16c80 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
16c90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
16ca0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
16cb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
16cc0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
16cd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16ce0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16cf0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16d00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16d10 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16d20 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16d30 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16d40 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16d60 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16d70 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16d80 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
16d90 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
16da0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
16db0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
16dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16dd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
16de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16df0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16e00 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16e20 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16e30 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16e40 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16e50 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16e60 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16e70 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16e80 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
16e90 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
16ea0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
16eb0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16ec0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
16ed0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16ee0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16ef0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16f10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16f20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16f30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16f40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16f60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16f70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16f80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
16f90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
16fa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
16fb0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
16fc0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
16fd0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
16fe0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16ff0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
17000 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
17010 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17020 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
17030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17040 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
17050 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
17060 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
17070 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
17080 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
17090 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
170a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
170b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
170c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
170d0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
170e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
170f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17100 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17120 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
17130 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17140 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
17150 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
17160 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
17170 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
17180 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
17190 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
171a0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
171d0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
171e0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
171f0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
17200 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
17210 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
17220 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
17230 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17240 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
17250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17260 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
17270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17280 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17290 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
172a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
172b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
172c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
172d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
172e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
172f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
17300 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
17310 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
17320 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
17330 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
17340 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
17350 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
17360 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
17370 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
17380 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
17390 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
173a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
173b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
173c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
173d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
173e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
173f0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
17400 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17410 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
17420 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17430 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
17440 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
17450 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
17460 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
17470 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
17480 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
17490 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
174a0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
174b0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
174c0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
174d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
174e0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
174f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17500 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
17510 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
17520 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
17530 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
17540 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
17550 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
17560 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
17570 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
17580 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
17590 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
175a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
175b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
175c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
175d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
175e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
175f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
17600 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
17610 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
17620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17630 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17650 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17660 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17680 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
17690 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
176a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
176b0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
176c0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
176d0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
176e0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
176f0 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
17700 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
17710 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
17720 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
17730 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
17740 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
17750 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
17760 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
17770 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
17780 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
17790 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
177a0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
177b0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
177c0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
177d0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
177e0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
177f0 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
17800 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
17810 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
17820 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
17830 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
17840 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
17850 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
17860 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
17870 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
17880 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
17890 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
178a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
178b0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
178c0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
178d0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
178e0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
178f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ime option..**.*
17900 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17910 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
17920 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17930 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
17940 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68  F_SIZE.** <dd>Th
17950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17960 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f  SORTERREF_SIZE o
17970 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20  ption accepts a 
17980 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17990 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74  .** of type (int
179a0 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75  ) - the new valu
179b0 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d  e of the sorter-
179c0 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74  reference size t
179d0 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75  hreshold..** Usu
179e0 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74  ally, when SQLit
179f0 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e  e uses an extern
17a00 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72  al sort to order
17a10 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69   records accordi
17a20 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45  ng.** to an ORDE
17a30 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c  R BY clause, all
17a40 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64   fields required
17a50 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61   by the caller a
17a60 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68  re present in th
17a70 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f  e.** sorted reco
17a80 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  rds. However, if
17a90 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17aa0 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20  es based on the 
17ab0 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a  declared type.**
17ac0 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   of a table colu
17ad0 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75  mn that its valu
17ae0 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f  es are likely to
17af0 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d   be very large -
17b00 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20   larger.** than 
17b10 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73  the configured s
17b20 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20  orter-reference 
17b30 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d  size threshold -
17b40 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63   then a referenc
17b50 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69  e.** is stored i
17b60 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65  n each sorted re
17b70 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71  cord and the req
17b80 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c  uired column val
17b90 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72  ues loaded.** fr
17ba0 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
17bb0 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72  as records are r
17bc0 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65  eturned in sorte
17bd0 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66  d order. The def
17be0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f  ault.** value fo
17bf0 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  r this option is
17c00 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68   to never use th
17c10 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  is optimization.
17c20 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a   Specifying a .*
17c30 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  * negative value
17c40 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
17c50 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65   restores the de
17c60 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e  fault behaviour.
17c70 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
17c80 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17c90 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
17ca0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
17cb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
17cc0 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45  LE_SORTER_REFERE
17cd0 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  NCES] compile-ti
17ce0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
17cf0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
17d10 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
17d20 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17d40 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
17d50 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17d70 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
17d80 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17da0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
17db0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
17dc0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17de0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
17df0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
17e00 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17e20 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
17e30 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
17e40 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
17e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17e60 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
17e70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
17e80 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
17e90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17ea0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
17eb0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
17ec0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
17ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ee0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17ef0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17f00 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17f20 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
17f30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17f40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17f60 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
17f70 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
17f80 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
17f90 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
17fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17fb0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17fc0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17fd0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17fe0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17ff0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18000 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18020 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18030 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18050 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18060 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18080 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18090 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
180a0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
180b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
180c0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
180d0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
180e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
180f0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18100 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18110 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18130 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18140 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18150 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18160 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18170 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18180 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18190 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
181a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
181b0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
181c0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
181d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
181e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
181f0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18200 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18210 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18230 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18240 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18250 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18260 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18280 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18290 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
182a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
182b0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
182c0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
182d0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
182e0 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
182f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18300 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
18310 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
18320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18330 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
18340 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
18350 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
18360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18370 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18380 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20  IZE      28  /* 
18390 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
183a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
183b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
183c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
183d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
183e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
183f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
18400 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
18410 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
18420 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
18430 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
18440 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
18450 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
18460 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
18470 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
18480 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18490 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
184a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
184b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
184c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
184d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
184e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
184f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
18500 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
18510 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
18520 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
18530 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18540 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
18550 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
18560 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
18570 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18580 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
18590 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
185a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
185b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
185c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
185d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
185e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
185f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
18600 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
18610 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18620 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
18630 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
18640 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
18650 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
18660 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
18670 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
18680 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18690 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
186a0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
186b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
186c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
186d0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
186e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
186f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18700 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
18710 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18720 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
18730 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
18740 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
18750 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
18760 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18770 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18780 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18790 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
187a0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
187b0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
187c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
187d0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
187e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
187f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18800 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
18810 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
18820 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
18830 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
18840 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
18850 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
18860 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18870 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18890 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
188a0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
188b0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
188c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
188d0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
188e0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
188f0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18900 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
18910 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
18920 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18930 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
18940 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18950 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
18960 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18970 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18980 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
18990 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
189a0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
189b0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
189c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
189d0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
189e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
189f0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
18a00 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
18a10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
18a20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
18a30 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
18a40 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
18a50 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
18a60 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18a70 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
18a90 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18ab0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
18ac0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
18ad0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
18ae0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18af0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
18b00 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
18b10 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
18b20 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
18b30 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
18b40 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
18b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
18b60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18b70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18b80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
18b90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18ba0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18bb0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18bc0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
18bd0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
18be0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
18bf0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
18c00 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18c10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18c20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18c30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18c40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18c50 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
18c60 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18c70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18c80 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18c90 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
18ca0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
18cb0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
18cc0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
18cd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18ce0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18cf0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18d00 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18d10 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18d20 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
18d30 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
18d40 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
18d50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18d60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18d70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18d80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18d90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
18da0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
18db0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18dc0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18dd0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18de0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18df0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
18e00 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18e10 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18e20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18e30 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
18e40 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
18e50 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18e60 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18e70 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18e80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18e90 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18ea0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18eb0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
18ec0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18ed0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
18ee0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18ef0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
18f00 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18f10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18f20 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18f30 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18f40 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18f50 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18f60 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18f70 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18f80 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18f90 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18fa0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18fb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18fc0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18fd0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18fe0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
18ff0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
19000 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
19010 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
19020 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19030 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
19040 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
19050 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19060 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19070 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19080 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
19090 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
190a0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
190b0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
190c0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
190d0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
190e0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
190f0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
19100 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19110 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19120 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19130 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19140 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19150 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19160 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
19170 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
19180 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19190 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
191a0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
191b0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
191c0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
191d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
191e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
191f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19200 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19210 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19220 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19230 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
19240 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
19250 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19260 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19270 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19280 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19290 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
192a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
192b0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
192c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
192d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
192e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
192f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19300 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
19310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19320 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19330 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19340 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
19350 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
19360 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
19370 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
19380 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
19390 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
193a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
193b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
193c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
193d0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
193e0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
193f0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
19400 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
19410 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
19420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
19430 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
19440 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19450 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19460 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19470 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
19480 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
19490 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
194a0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
194b0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
194c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
194d0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
194e0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
194f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19500 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
19510 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
19520 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
19530 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
19540 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
19550 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
19560 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
19570 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
19580 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
19590 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
195a0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
195b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
195c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
195d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
195e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
195f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19600 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19610 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19620 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
19630 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
19640 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
19650 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
19660 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
19670 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19690 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
196a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
196b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
196c0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
196d0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
196e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
196f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19700 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
19710 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
19720 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
19730 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
19740 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
19750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
19760 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19770 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19780 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
19790 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
197a0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
197b0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
197c0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
197d0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
197e0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
197f0 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
19800 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
19810 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
19820 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
19830 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
19840 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
19850 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
19860 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19870 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19880 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
19890 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
198a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
198b0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
198c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
198d0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
198e0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
198f0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
19900 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
19910 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
19920 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
19930 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
19940 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
19950 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
19960 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19970 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19980 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
19990 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
199a0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
199b0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
199c0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
199d0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
199e0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
199f0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
19a00 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
19a10 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
19a20 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
19a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19a40 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19a50 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
19a60 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73  an integer - pos
19a70 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65  itive to disable
19a80 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19a90 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
19aa0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
19ab0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20  to enable them, 
19ac0 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20  and negative to 
19ad0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
19ae0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
19af0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19b00 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19b10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
19b20 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
19b30 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19b40 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19b50 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
19b60 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
19b70 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19b80 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
19b90 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19ba0 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19bb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19bc0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19bd0 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
19be0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
19bf0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c00 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
19c10 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
19c20 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
19c30 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
19c40 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
19c50 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
19c60 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
19c70 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
19c80 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
19c90 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
19ca0 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
19cb0 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
19cc0 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
19cd0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
19ce0 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
19cf0 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
19d00 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
19d10 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
19d20 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
19d30 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
19d40 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
19d50 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
19d60 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
19d70 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
19d80 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
19d90 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
19da0 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
19db0 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
19dc0 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
19dd0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
19de0 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
19df0 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
19e00 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
19e10 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
19e20 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72   lab..** The fir
19e30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19e40 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
19e50 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19e60 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19e70 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f  .** the QPSG, po
19e80 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19e90 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69   QPSG, or negati
19ea0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19eb0 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
19ec0 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64  nged. The second
19ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ee0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19ef0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19f00 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19f10 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19f20 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50  e whether the QP
19f30 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  SG is disabled o
19f40 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
19f50 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19f60 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
19f90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79  </dt>.** <dd> By
19fa0 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75   default, the ou
19fb0 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20  tput of EXPLAIN 
19fc0 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61  QUERY PLAN comma
19fd0 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a  nds does not .**
19fe0 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20   include output 
19ff0 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f  for any operatio
1a000 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ns performed by 
1a010 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1a020 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e  . This.** option
1a030 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
1a040 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65  or clear (the de
1a050 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68  fault) a flag th
1a060 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a  at governs this.
1a070 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65  ** behavior. The
1a080 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a090 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
1a0a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1a0b0 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73  integer -.** pos
1a0c0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1a0d0 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67  output for trigg
1a0e0 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20  er programs, or 
1a0f0 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
1a100 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69  it,.** or negati
1a110 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
1a120 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
1a130 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
1a140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a150 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1a160 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1a170 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20   is written .** 
1a180 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1a190 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75  te whether outpu
1a1a0 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68  t-for-triggers h
1a1b0 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  as been disabled
1a1c0 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69   - 0 if .** it i
1a1d0 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  s not disabled, 
1a1e0 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a  1 if it is.  .**
1a1f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
1a200 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a210 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c  _RESET_DATABASE<
1a220 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74  /dt>.** <dd> Set
1a230 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
1a240 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1a250 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65  ASE flag and the
1a260 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d  n run.** [VACUUM
1a270 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  ] in order to re
1a280 73 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62  set a database b
1a290 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ack to an empty 
1a2a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68  database.** with
1a2b0 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e   no schema and n
1a2c0 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66  o content. The f
1a2d0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73  ollowing process
1a2e0 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a   works even for.
1a2f0 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75  ** a badly corru
1a300 70 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69  pted database fi
1a310 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  le:.** <ol>.** <
1a320 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1a330 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1a340 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1a350 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b  DATABASE, 1, 0);
1a360 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  .** <li> [sqlite
1a370 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41  3_exec](db, "[VA
1a380 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29  CUUM]", 0, 0, 0)
1a390 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ;.** <li> sqlite
1a3a0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1a3b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a3c0 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1a3d0 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  0, 0);.** </ol>.
1a3e0 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74  ** Because reset
1a3f0 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ting a database 
1a400 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61  is destructive a
1a410 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c  nd irreversible,
1a420 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20   the.** process 
1a430 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65  requires the use
1a440 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65   of this obscure
1a450 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c   API and multipl
1a460 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a  e steps to help.
1a470 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69  ** ensure that i
1a480 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65  t does not happe
1a490 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a  n by accident..*
1a4a0 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  * </dd>.** </dl>
1a4b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a4c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a4d0 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
1a4e0 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
1a4f0 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
1a500 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a510 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
1a520 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
1a530 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
1a540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a550 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
1a560 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
1a570 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
1a580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a590 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a5a0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1a5b0 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
1a5c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a5d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a5e0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
1a5f0 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
1a600 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1a610 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a620 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
1a630 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
1a640 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1a650 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a660 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
1a670 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
1a680 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1a690 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1a6a0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
1a6b0 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
1a6c0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1a6d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1a6e0 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20  FIG_TRIGGER_EQP 
1a6f0 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
1a700 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1a710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1a720 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1a730 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30 39  BASE        1009
1a740 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1a750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a760 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20  BCONFIG_MAX     
1a770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1a780 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42  09 /* Largest DB
1a790 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  CONFIG */../*.**
1a7a0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1a7b0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1a7c0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1a7d0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1a7e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1a7f0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1a800 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1a810 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1a820 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1a830 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1a840 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1a850 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1a860 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1a870 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1a880 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1a890 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1a8a0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1a8b0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1a8c0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
1a8d0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
1a8e0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1a8f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1a900 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1a910 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a920 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
1a930 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
1a940 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
1a950 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
1a960 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
1a970 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
1a980 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
1a990 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
1a9a0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
1a9b0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
1a9c0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
1a9d0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
1a9e0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
1a9f0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
1aa00 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
1aa10 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
1aa20 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
1aa30 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
1aa40 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1aa50 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
1aa60 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
1aa70 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
1aa80 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
1aa90 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
1aaa0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
1aab0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
1aac0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
1aad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1aae0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1aaf0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
1ab00 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
1ab10 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
1ab20 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
1ab30 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
1ab40 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
1ab50 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
1ab60 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
1ab70 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
1ab80 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
1ab90 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
1aba0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
1abb0 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
1abc0 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
1abd0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
1abe0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1abf0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1ac00 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
1ac10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ac20 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
1ac30 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1ac40 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1ac50 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
1ac60 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
1ac70 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
1ac80 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
1ac90 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
1aca0 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
1acb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1acc0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1acd0 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
1ace0 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
1acf0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1ad00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1ad10 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
1ad20 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1ad30 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1ad40 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
1ad50 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
1ad60 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
1ad70 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
1ad80 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
1ad90 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
1ada0 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
1adb0 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
1adc0 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
1add0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
1ade0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1adf0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
1ae00 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1ae10 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
1ae20 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
1ae30 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
1ae40 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
1ae50 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
1ae60 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1ae70 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
1ae80 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
1ae90 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
1aea0 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
1aeb0 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
1aec0 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
1aed0 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
1aee0 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
1aef0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1af00 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
1af10 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
1af20 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
1af30 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
1af40 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1af50 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1af60 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
1af70 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
1af80 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1af90 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1afa0 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
1afb0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
1afc0 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
1afd0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1afe0 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
1aff0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b000 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1b010 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1b020 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1b030 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
1b040 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
1b050 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
1b060 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
1b070 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1b080 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
1b090 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
1b0a0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
1b0b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1b0c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b0d0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
1b0e0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
1b0f0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
1b100 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
1b110 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
1b120 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
1b130 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
1b140 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
1b150 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1b160 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
1b170 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
1b180 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
1b190 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
1b1a0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
1b1b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
1b1c0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
1b1d0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
1b1e0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
1b1f0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
1b200 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
1b210 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
1b220 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
1b230 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
1b240 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1b250 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
1b260 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
1b270 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1b280 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
1b290 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
1b2a0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
1b2b0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
1b2c0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
1b2d0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
1b2e0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
1b2f0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
1b300 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
1b310 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1b320 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
1b330 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
1b340 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
1b350 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1b360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1b370 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1b380 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
1b390 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
1b3a0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
1b3b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1b3c0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
1b3d0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1b3e0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1b3f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1b400 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
1b410 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
1b420 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
1b430 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
1b440 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1b450 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1b460 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
1b470 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b480 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
1b490 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
1b4a0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
1b4b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1b4c0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
1b4d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1b4e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b4f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b500 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1b510 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1b520 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1b530 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b540 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b550 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1b560 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1b570 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1b580 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1b590 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1b5a0 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1b5b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1b5c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1b5d0 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1b5e0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1b5f0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1b600 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
1b610 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1b620 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1b630 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
1b640 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1b650 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1b660 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1b670 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1b680 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b690 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1b6a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1b6b0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1b6c0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1b6d0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1b6e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1b6f0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1b700 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1b710 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1b720 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1b730 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1b740 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1b750 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1b760 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1b770 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1b780 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1b790 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1b7a0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1b7b0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1b7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1b7d0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1b7e0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1b7f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1b800 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1b810 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1b820 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1b830 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1b840 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1b850 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1b860 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1b870 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1b880 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1b890 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1b8a0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1b8b0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1b8c0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1b8d0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1b8e0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b8f0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1b900 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1b910 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1b920 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1b930 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1b940 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1b950 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1b960 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1b970 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1b980 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1b990 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1b9a0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1b9b0 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1b9c0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1b9d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1b9e0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1b9f0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1ba00 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1ba10 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1ba20 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1ba30 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1ba40 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1ba50 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1ba60 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1ba70 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1ba80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1ba90 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1baa0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1bab0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1bac0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1bad0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1bae0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1baf0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1bb00 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1bb10 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1bb20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1bb30 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1bb40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1bb50 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1bb60 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1bb70 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1bb80 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1bb90 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1bba0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1bbb0 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1bbc0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1bbd0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1bbe0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1bbf0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1bc00 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1bc10 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1bc20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1bc30 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1bc40 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1bc50 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1bc60 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1bc70 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1bc80 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1bc90 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1bca0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1bcb0 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1bcc0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1bcd0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1bce0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1bcf0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1bd00 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1bd10 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1bd20 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1bd30 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1bd40 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1bd50 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1bd60 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1bd70 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1bd80 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1bd90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1bda0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1bdb0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1bdc0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1bdd0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1bde0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1bdf0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1be00 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1be10 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1be20 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1be30 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1be40 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1be50 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1be60 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1be70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1be80 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1be90 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1bea0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1beb0 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1bec0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1bed0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1bee0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1bef0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bf00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1bf10 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1bf20 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1bf30 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1bf40 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1bf50 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1bf60 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1bf70 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1bf80 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1bf90 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1bfa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bfb0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1bfc0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1bfd0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1bfe0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1bff0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1c000 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1c010 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1c020 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1c030 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1c040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1c050 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1c060 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1c070 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c080 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c090 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1c0a0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1c0b0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1c0c0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1c0d0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1c0e0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1c0f0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1c100 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1c110 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1c120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c130 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1c140 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1c150 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1c160 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1c170 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1c180 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1c190 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1c1a0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1c1b0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1c1c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c1d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1c1e0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1c1f0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1c200 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1c210 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1c220 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1c230 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1c240 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1c250 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1c260 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1c270 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1c280 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1c290 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1c2a0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1c2b0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1c2c0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1c2d0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1c2e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1c2f0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1c300 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1c310 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1c320 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1c330 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1c340 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1c350 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1c360 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1c370 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1c380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c390 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1c3a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1c3b0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1c3c0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1c3d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1c3e0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1c3f0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1c400 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1c410 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1c420 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1c430 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1c440 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1c450 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1c460 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c470 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1c480 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1c490 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1c4a0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1c4b0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1c4c0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1c4d0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1c4e0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1c4f0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1c500 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1c510 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1c520 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1c530 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1c540 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1c550 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1c560 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1c570 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1c580 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1c590 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1c5a0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1c5b0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1c5c0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1c5d0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1c5e0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1c5f0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1c600 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1c610 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1c620 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1c630 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1c640 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c650 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1c660 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1c670 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1c680 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1c690 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1c6a0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1c6b0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1c6c0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1c6d0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1c6e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1c6f0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1c700 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1c710 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1c720 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1c730 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1c740 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1c750 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1c760 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1c770 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1c780 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1c790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1c7a0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1c7b0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1c7c0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1c7d0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1c7e0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1c7f0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1c800 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1c810 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1c820 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1c830 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1c840 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1c850 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1c860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1c870 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1c880 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1c890 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1c8a0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1c8b0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1c8c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c8d0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1c8e0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1c8f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1c900 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1c910 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1c920 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1c930 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1c940 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1c950 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1c960 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1c970 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1c980 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1c990 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1c9a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c9b0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1c9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1c9d0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1c9e0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1c9f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1ca00 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1ca10 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1ca20 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1ca30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1ca40 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1ca50 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ca60 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1ca70 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1ca80 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1ca90 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1caa0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1cab0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1cac0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1cad0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1cae0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1caf0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1cb00 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f  l returns..*/.vo
1cb10 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1cb20 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1cb30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cb40 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1cb50 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1cb60 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1cb70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1cb80 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1cb90 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1cba0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1cbb0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1cbc0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1cbd0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1cbe0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1cbf0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1cc00 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1cc10 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1cc20 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1cc30 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1cc40 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1cc50 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1cc60 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1cc70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1cc80 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1cc90 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1cca0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1ccb0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1ccc0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1ccd0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1cce0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ccf0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1cd00 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1cd10 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1cd20 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1cd30 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1cd40 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1cd50 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1cd60 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1cd70 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1cd80 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1cd90 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1cda0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1cdb0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1cdc0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1cdd0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1cde0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1cdf0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1ce00 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1ce10 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1ce20 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1ce30 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1ce40 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1ce50 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1ce60 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1ce70 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1ce80 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1ce90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1cea0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1ceb0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1cec0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1ced0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1cee0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1cef0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1cf00 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1cf10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1cf20 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1cf30 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1cf40 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1cf50 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1cf60 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1cf70 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1cf80 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1cf90 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1cfa0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1cfb0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1cfc0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1cfd0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1cfe0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1cff0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1d000 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1d010 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1d020 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1d030 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1d040 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1d050 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1d060 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1d070 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1d080 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1d090 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1d0a0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1d0b0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1d0c0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1d0d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1d0e0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1d0f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d100 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1d110 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1d120 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1d130 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1d140 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1d150 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1d160 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1d170 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1d180 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1d190 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1d1a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1d1b0 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1d1c0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1d1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1d1e0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1d1f0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1d200 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1d210 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1d220 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1d230 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1d240 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1d250 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1d260 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d270 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1d280 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1d290 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1d2a0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1d2b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1d2c0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1d2d0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1d2e0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1d2f0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1d300 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1d310 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1d320 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1d330 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1d340 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1d350 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1d360 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1d370 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1d380 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d390 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1d3a0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1d3b0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1d3c0 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1d3d0 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1d3e0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1d3f0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1d400 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1d410 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1d420 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1d430 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1d440 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1d450 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1d460 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1d470 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d480 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1d490 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1d4a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1d4b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1d4c0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1d4d0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1d4e0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1d4f0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1d500 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1d510 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1d520 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1d530 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1d540 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1d550 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1d560 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1d570 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1d580 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1d590 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1d5a0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1d5b0 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1d5c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1d5d0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1d5e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1d5f0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1d600 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1d610 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1d620 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1d630 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1d640 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1d650 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1d660 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1d670 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d680 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1d690 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1d6a0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1d6b0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1d6c0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1d6d0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1d6e0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1d6f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1d700 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1d710 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1d720 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1d730 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1d740 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1d750 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1d760 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1d770 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1d780 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1d790 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1d7a0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1d7b0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1d7c0 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1d7d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1d7e0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1d7f0 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1d800 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1d810 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1d820 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1d830 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1d840 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1d850 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1d860 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1d870 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1d880 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1d890 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1d8a0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1d8b0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1d8c0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1d8d0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1d8e0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1d8f0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1d900 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1d910 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1d920 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1d930 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1d940 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1d950 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1d960 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1d970 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1d980 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1d990 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1d9a0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1d9b0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1d9c0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1d9d0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1d9e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d9f0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1da00 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1da10 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1da20 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1da30 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1da40 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1da50 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1da60 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1da70 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1da80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1da90 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1daa0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1dab0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1dac0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1dad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1dae0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1daf0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1db00 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1db10 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1db20 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1db30 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1db40 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1db50 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1db60 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1db70 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1db80 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1db90 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1dba0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1dbb0 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1dbc0 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1dbd0 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1dbe0 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1dbf0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1dc00 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1dc10 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1dc20 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1dc30 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1dc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1dc50 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1dc60 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1dc70 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1dc80 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1dc90 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1dca0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1dcb0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1dcc0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1dcd0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1dce0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1dcf0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1dd00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dd10 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1dd20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1dd30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1dd40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1dd50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1dd60 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1dd70 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1dd80 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1dd90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1dda0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1ddb0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1ddc0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ddd0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1dde0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1ddf0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1de00 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1de10 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1de20 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1de30 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1de40 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1de50 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1de60 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1de70 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1de80 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1de90 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1dea0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1deb0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1dec0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1ded0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1dee0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1def0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1df00 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1df10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1df20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1df30 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1df40 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1df50 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1df60 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1df70 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1df80 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1df90 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1dfa0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1dfb0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1dfc0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1dfd0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1dfe0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1dff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1e000 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1e010 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1e020 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1e030 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1e040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1e050 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1e060 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1e070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1e080 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1e090 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1e0a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1e0b0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1e0c0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1e0d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1e0e0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1e0f0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1e100 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1e110 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1e120 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1e130 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1e140 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1e150 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1e160 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1e170 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1e180 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1e190 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1e1a0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1e1b0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1e1c0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1e1d0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1e1e0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1e1f0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1e200 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1e210 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1e220 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1e230 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1e240 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1e250 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1e260 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1e270 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1e280 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1e290 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1e2a0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1e2b0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1e2c0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1e2d0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1e2e0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1e2f0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1e300 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1e310 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1e320 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1e330 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1e340 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1e350 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1e360 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1e370 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1e380 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1e390 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1e3a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1e3b0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1e3c0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1e3d0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1e3e0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1e3f0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1e400 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1e410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1e420 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1e430 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1e440 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1e450 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1e460 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1e470 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1e480 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1e490 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1e4a0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1e4b0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1e4c0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1e4d0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1e4e0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1e4f0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1e500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1e510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1e520 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1e530 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1e540 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1e550 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1e560 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1e570 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1e580 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1e590 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1e5a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1e5b0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1e5c0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1e5d0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1e5e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1e5f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1e600 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1e610 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1e620 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1e630 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1e640 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1e650 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e660 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1e670 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1e680 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1e690 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e6a0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1e6b0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1e6c0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1e6d0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1e6e0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1e6f0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1e700 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e710 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1e720 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1e730 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1e740 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1e750 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1e760 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1e770 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1e780 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1e790 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1e7a0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1e7b0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1e7c0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1e7d0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1e7e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e7f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e800 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1e810 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e820 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1e830 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1e840 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1e850 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1e860 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e870 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1e880 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e890 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1e8a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e8b0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1e8c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e8d0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1e8e0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1e8f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1e900 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1e910 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1e920 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1e930 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e940 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1e950 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1e960 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1e970 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1e980 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1e990 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1e9a0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1e9b0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1e9c0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1e9d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1e9e0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1e9f0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1ea00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ea10 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1ea20 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1ea30 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1ea40 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1ea50 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1ea60 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1ea70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1ea80 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1ea90 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1eaa0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1eab0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1eac0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1ead0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1eae0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1eaf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1eb00 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1eb10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1eb20 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1eb30 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1eb40 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1eb50 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1eb60 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1eb70 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1eb80 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1eb90 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1eba0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1ebb0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1ebc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ebd0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1ebe0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1ebf0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1ec00 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1ec10 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1ec20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1ec30 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1ec40 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1ec50 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1ec60 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1ec70 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1ec80 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1ec90 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1eca0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1ecb0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1ecc0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1ecd0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1ece0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1ecf0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1ed00 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1ed10 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1ed20 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1ed30 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1ed40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ed50 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1ed60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1ed70 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1ed80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1ed90 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1eda0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1edb0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1edc0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1edd0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1ede0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1edf0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1ee00 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1ee10 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1ee20 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1ee30 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1ee40 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1ee50 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1ee60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1ee70 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1ee80 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1ee90 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1eea0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1eeb0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1eec0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1eed0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1eee0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1eef0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1ef00 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1ef10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ef20 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1ef30 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1ef40 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ef50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1ef60 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1ef70 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1ef80 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1ef90 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1efa0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1efb0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1efc0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1efd0 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1efe0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1eff0 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ons from.** the 
1f000 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
1f010 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c   printf() .** pl
1f020 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1f030 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1f040 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b  formats ([%q], [
1f050 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b  %Q], [%w], and [
1f060 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65  %z])..** See the
1f070 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74   [built-in print
1f080 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  f()] documentati
1f090 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a  on for details..
1f0a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f0b0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1f0c0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1f0d0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1f0e0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1f0f0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1f100 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1f110 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f120 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1f130 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1f140 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1f150 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1f160 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1f170 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1f180 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1f190 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1f1a0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1f1b0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73  3_malloc64()] is
1f1c0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1f1d0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1f1e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1f1f0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1f200 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1f210 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f220 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1f230 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1f240 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1f250 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1f260 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1f270 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1f280 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1f290 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1f2a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1f2b0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1f2c0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1f2d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1f2e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1f2f0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1f300 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1f310 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1f320 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1f330 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1f340 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1f350 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1f360 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1f370 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1f380 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f390 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1f3a0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1f3b0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1f3c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1f3d0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1f3e0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1f3f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1f400 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1f410 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1f420 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1f430 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1f440 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1f450 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1f460 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1f470 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1f480 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1f490 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1f4a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1f4b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1f4c0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1f4d0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1f4e0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1f4f0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1f500 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1f510 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1f520 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f530 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1f540 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1f550 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1f560 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1f570 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1f580 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1f590 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1f5a0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1f5b0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1f5c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1f5d0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1f5e0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1f5f0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1f600 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1f610 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1f620 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1f630 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1f640 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1f650 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1f660 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1f670 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1f680 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c  See also:  [buil
1f690 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20  t-in printf()], 
1f6a0 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75  [printf() SQL fu
1f6b0 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20  nction].*/.char 
1f6c0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1f6d0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1f6e0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1f6f0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f700 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f710 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1f720 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f730 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f740 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1f750 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f760 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f770 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f790 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f7a0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f7b0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f7c0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f7d0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f7e0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f7f0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f810 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1f820 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1f830 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1f840 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1f850 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1f860 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f870 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1f880 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1f890 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1f8a0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1f8b0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1f8c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f8d0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1f8e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1f8f0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1f900 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1f910 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1f920 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1f930 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1f940 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f950 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1f960 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1f970 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1f980 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1f990 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f9a0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1f9b0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1f9c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f9d0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1f9e0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1f9f0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1fa00 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1fa10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1fa20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1fa30 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1fa40 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1fa50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1fa60 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1fa70 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1fa80 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1fa90 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1faa0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1fab0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1fac0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1fad0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1fae0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1faf0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1fb00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1fb10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fb20 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1fb30 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1fb40 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1fb50 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1fb60 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1fb70 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1fb80 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1fb90 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1fba0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1fbb0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1fbc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1fbd0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1fbe0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1fbf0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1fc00 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1fc10 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1fc20 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1fc30 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1fc40 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1fc50 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1fc60 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1fc70 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1fc80 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1fc90 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1fca0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1fcb0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fcc0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1fcd0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1fce0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1fcf0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1fd00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1fd10 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1fd20 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1fd30 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1fd40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1fd50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fd60 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1fd70 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1fd80 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1fd90 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1fda0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1fdb0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1fdc0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1fdd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1fde0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fdf0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1fe00 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1fe10 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1fe20 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1fe30 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fe40 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1fe50 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1fe60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fe70 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1fe80 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1fe90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1fea0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1feb0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1fec0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1fed0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1fee0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1fef0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ff00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ff10 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1ff20 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1ff30 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1ff40 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1ff50 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1ff60 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1ff70 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1ff80 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1ff90 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1ffa0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1ffb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1ffc0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1ffd0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1ffe0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1fff0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
20000 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
20010 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
20020 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
20030 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
20040 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
20050 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
20060 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
20070 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
20080 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
20090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
200a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
200b0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
200c0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
200d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
200e0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
200f0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
20100 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
20110 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
20120 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
20130 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
20140 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
20150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
20160 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
20170 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
20180 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
20190 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
201a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
201b0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
201c0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
201d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
201e0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
201f0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
20200 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
20210 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
20220 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
20230 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
20240 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
20250 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
20260 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
20270 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
20280 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
20290 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
202a0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
202b0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
202c0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
202d0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
202e0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
202f0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
20300 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
20310 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
20320 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
20330 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
20340 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
20350 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
20360 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
20370 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20380 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
20390 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
203a0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
203b0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
203c0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
203d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
203e0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
203f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
20400 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
20410 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
20420 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
20430 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
20440 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
20450 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
20460 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
20470 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
20480 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
20490 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
204a0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
204b0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
204c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
204d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
204e0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
204f0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
20500 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
20510 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
20520 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
20530 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
20540 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
20550 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
20560 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
20570 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
20580 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
20590 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
205a0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
205b0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
205c0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
205d0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
205e0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
205f0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
20600 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
20610 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
20620 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
20630 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
20640 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
20650 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
20660 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
20670 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
20680 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
20690 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
206a0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
206b0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
206c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
206d0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
206e0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
206f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
20700 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
20710 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
20720 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
20730 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
20740 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
20750 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
20760 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
20770 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
20780 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
20790 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
207a0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
207b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
207c0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
207d0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
207e0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
207f0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
20800 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
20810 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20820 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20830 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
20840 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
20850 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
20860 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
20870 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
20880 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
20890 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
208a0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
208b0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
208c0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
208d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
208e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
208f0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
20900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
20910 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
20920 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
20930 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20940 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20950 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
20960 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
20970 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
20980 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
20990 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
209a0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
209b0 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
209c0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
209d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
209e0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
209f0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
20a00 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
20a10 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
20a20 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
20a30 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
20a40 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
20a50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
20a60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20a70 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20a80 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
20a90 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
20aa0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
20ab0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20ac0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
20ad0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
20ae0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20af0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20b00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20b10 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
20b20 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
20b30 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
20b40 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
20b50 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
20b60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20b70 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
20b80 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
20b90 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
20ba0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20bb0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
20bc0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20bd0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
20be0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
20bf0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
20c00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20c10 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
20c20 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20c30 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
20c40 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
20c50 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
20c60 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
20c70 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20c80 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
20c90 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
20ca0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20cb0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
20cc0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
20cd0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
20ce0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20cf0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
20d00 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
20d10 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
20d20 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
20d30 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
20d40 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20d50 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
20d60 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
20d70 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
20d80 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20d90 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
20da0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20db0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
20dc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20dd0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
20de0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20df0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
20e00 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
20e10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
20e20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
20e30 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
20e40 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20e50 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
20e60 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
20e70 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
20e80 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
20e90 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
20ea0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
20eb0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
20ec0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20ed0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
20ee0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
20ef0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
20f00 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
20f10 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20f20 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20f30 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20f40 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20f50 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20f60 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
20f70 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
20f80 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
20f90 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
20fa0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
20fb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
20fc0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20fd0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
20fe0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
20ff0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
21000 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
21010 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
21020 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
21030 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
21040 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
21050 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
21060 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
21070 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
21080 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
21090 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
210a0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
210b0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
210c0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
210d0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
210e0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
210f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
21100 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
21110 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
21120 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
21130 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
21140 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
21150 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
21160 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
21170 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
21180 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
21190 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
211a0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
211b0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
211c0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
211d0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
211e0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
211f0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
21200 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
21210 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
21220 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
21230 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
21240 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
21250 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
21260 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
21270 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
21280 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
21290 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
212a0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
212b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
212c0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f  KEYWORDS: {autho
212d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a  rizer callback}.
212e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
212f0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
21300 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21310 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
21320 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
21330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
21340 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
21350 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
21360 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
21370 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21380 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
21390 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
213a0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
213b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
213c0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
213d0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
213e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
213f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21400 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
21410 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
21420 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21430 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e  e16_v2()],.** an
21440 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
21450 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74  re16_v3()].  ^At
21460 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
21470 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
21480 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
21490 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
214a0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
214b0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
214c0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
214d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
214e0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
214f0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
21500 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
21510 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
21520 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21530 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
21540 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
21550 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
21560 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
21570 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
21580 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
21590 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
215a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
215b0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
215c0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
215d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
215e0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
215f0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
21600 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
21610 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
21620 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
21630 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21640 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
21650 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
21660 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
21670 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
21680 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
21690 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
216a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
216b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
216c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
216d0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
216e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
216f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
21700 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
21710 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21720 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21730 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
21740 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
21750 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
21760 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
21770 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21780 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
21790 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
217a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
217b0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
217c0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
217d0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
217e0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
217f0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
21800 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
21810 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
21820 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
21830 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21840 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
21850 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
21860 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
21870 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
21880 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
21890 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
218a0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
218b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
218c0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
218d0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
218e0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
218f0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
21900 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
21910 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
21920 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21930 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
21940 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
21950 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
21960 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
21970 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
21980 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
21990 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
219a0 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
219b0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
219c0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
219d0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
219e0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
219f0 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
21a00 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
21a10 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
21a20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
21a30 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
21a40 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
21a50 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
21a60 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
21a70 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
21a80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
21a90 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21aa0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
21ab0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21ac0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
21ad0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
21ae0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21af0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
21b00 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
21b10 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
21b20 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
21b30 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
21b40 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
21b50 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
21b60 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
21b70 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
21b80 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21b90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
21ba0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
21bb0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
21bc0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
21bd0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
21be0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
21bf0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
21c00 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
21c10 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
21c20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
21c30 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
21c40 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
21c50 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
21c60 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
21c70 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
21c80 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
21c90 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
21ca0 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
21cb0 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
21cc0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
21cd0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
21ce0 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
21cf0 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
21d00 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
21d10 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
21d20 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
21d30 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
21d40 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21d50 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
21d60 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21d70 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
21d80 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
21d90 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
21da0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21db0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
21dc0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
21dd0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
21de0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
21df0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
21e00 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
21e10 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
21e20 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
21e30 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
21e40 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
21e50 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
21e60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21e70 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
21e80 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
21e90 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
21ea0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21eb0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
21ec0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
21ed0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
21ee0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
21ef0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
21f00 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
21f10 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
21f20 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
21f30 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
21f40 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21f50 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21f60 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21f70 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21f80 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21f90 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21fa0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21fb0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21fc0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21fd0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21fe0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
21ff0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
22000 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
22010 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
22020 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
22030 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
22040 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
22050 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
22060 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
22070 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
22080 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
22090 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
220a0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
220b0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
220c0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
220d0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
220e0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
220f0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
22100 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
22110 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
22120 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
22130 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
22140 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
22150 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
22160 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
22170 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
22180 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
22190 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
221a0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
221b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
221c0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
221d0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
221e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
221f0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
22200 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
22210 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
22220 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
22230 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
22240 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
22250 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
22260 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
22270 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
22280 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22290 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
222a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
222b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
222c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
222d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
222e0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
222f0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
22300 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
22310 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
22320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
22330 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
22340 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
22350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
22360 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
22370 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
22380 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
22390 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
223a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
223b0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
223c0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
223d0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
223e0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
223f0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
22400 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
22410 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
22420 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
22430 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
22440 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
22450 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
22460 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
22470 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
22480 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
22490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
224a0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
224b0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
224c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
224d0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
224e0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
224f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
22500 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
22510 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
22520 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
22530 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
22540 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
22550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22560 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
22570 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
22580 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
22590 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
225a0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
225b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
225c0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
225d0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
225e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
225f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
22600 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
22610 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
22620 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
22630 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
22640 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
22650 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
22660 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
22670 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
22680 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22690 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
226a0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
226b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
226c0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
226d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
226e0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
226f0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
22700 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
22710 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
22720 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
22730 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
22740 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
22750 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
22760 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
22770 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22780 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
22790 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
227a0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
227b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
227c0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
227d0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
227e0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
227f0 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
22800 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
22810 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
22820 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
22830 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
22840 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
22850 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
22860 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
22870 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
22880 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
22890 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
228a0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
228b0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
228c0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
228d0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
228e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
228f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22900 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
22910 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22920 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22930 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
22940 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
22950 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22960 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
22970 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
22980 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
22990 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
229a0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
229b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
229c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
229d0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
229e0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
229f0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
22a00 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
22a10 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
22a20 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
22a30 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
22a40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22a50 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
22a60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
22a70 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
22a80 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
22a90 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
22aa0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
22ab0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
22ac0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
22ad0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
22ae0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
22af0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
22b00 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
22b10 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
22b20 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
22b30 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
22b40 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
22b50 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
22b60 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
22b70 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
22b80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22b90 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
22ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
22bb0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
22bc0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
22bd0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
22be0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22bf0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22c00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
22c10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
22c20 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
22c30 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
22c40 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
22c50 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
22c60 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
22c70 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
22c80 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
22c90 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
22ca0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
22cb0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
22cc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22cd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
22ce0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
22cf0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
22d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22d10 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
22d20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
22d30 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22d40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22d60 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
22d70 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
22d80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22d90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22db0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
22dc0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
22dd0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22de0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22df0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22e00 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
22e10 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
22e20 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22e30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22e40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22e50 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
22e60 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
22e70 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22e80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22e90 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22ea0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22eb0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
22ec0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22ed0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22ee0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22ef0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
22f00 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22f10 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22f20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22f30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22f40 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
22f50 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22f60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22f70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22f80 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
22f90 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
22fa0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22fb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22fc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22fd0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
22fe0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
22ff0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23000 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23010 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23020 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
23030 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
23040 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23050 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23060 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23070 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
23080 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
23090 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
230a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
230b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
230c0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
230d0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
230e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
230f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23110 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
23120 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
23130 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
23140 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23160 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
23170 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
23180 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
23190 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
231a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
231b0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
231c0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
231d0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
231e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
231f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23200 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
23210 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
23220 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
23230 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
23250 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
23260 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
23270 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23280 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
232a0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
232b0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
232c0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
232d0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
232e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
232f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23300 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
23310 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
23320 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
23330 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
23340 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
23350 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
23360 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
23370 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23380 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
23390 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
233a0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
233b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
233c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
233d0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
233e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
233f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23400 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
23410 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
23420 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
23430 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
23440 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
23450 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23460 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23470 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
23480 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
23490 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
234a0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
234b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
234c0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
234d0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
234e0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
234f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23500 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23510 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
23520 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
23530 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23540 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23550 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23560 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
23570 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
23580 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23590 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
235a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
235b0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
235c0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
235d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
235e0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
235f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23600 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
23610 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
23620 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
23630 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
23640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23650 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
23660 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
23670 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
23680 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
23690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
236a0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
236b0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
236c0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
236d0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
236e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
236f0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
23700 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
23710 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
23720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
23730 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
23740 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
23750 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
23760 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
23770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
23780 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
23790 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
237a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
237b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
237c0 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
237d0 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
237e0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
237f0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
23800 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
23810 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
23820 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
23830 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
23840 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
23850 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
23860 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
23870 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
23880 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
23890 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
238a0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
238b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
238c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
238d0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
238e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
238f0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
23900 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
23910 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
23920 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
23930 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
23940 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
23950 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
23960 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
23970 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
23980 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
23990 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
239a0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
239b0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
239c0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
239d0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
239e0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
239f0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
23a00 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
23a10 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
23a20 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
23a30 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
23a40 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
23a50 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
23a60 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
23a70 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
23a80 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
23a90 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
23aa0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
23ab0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
23ac0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
23ad0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
23ae0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
23af0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
23b00 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
23b10 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
23b20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23b30 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23b40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
23b50 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
23b60 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
23b70 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
23b80 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
23b90 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
23ba0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23bb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
23bc0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
23bd0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
23be0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
23bf0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
23c00 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
23c10 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23c20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23c30 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23c40 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
23c50 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
23c60 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
23c70 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
23c80 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
23c90 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
23ca0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23cb0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
23cc0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
23cd0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
23ce0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23cf0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23d00 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
23d10 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23d20 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23d30 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23d40 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
23d50 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
23d60 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
23d70 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
23d80 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
23d90 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
23da0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23db0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
23dc0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23dd0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
23de0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23df0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
23e00 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
23e10 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23e20 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
23e30 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
23e40 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
23e50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
23e60 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
23e70 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
23e80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e90 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
23ea0 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
23eb0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
23ec0 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
23ed0 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
23ee0 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
23ef0 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
23f00 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
23f10 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
23f20 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
23f30 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
23f40 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74   M argument.** t
23f50 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
23f60 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73  _v2(D,M,X,P)] is
23f70 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e   an OR-ed combin
23f80 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20  ation of one or 
23f90 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  more of.** the f
23fa0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
23fb0 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ts.  ^The first 
23fc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
23fd0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
23fe0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  * is one of the 
23ff0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
24000 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74  nts..**.** New t
24010 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  racing constants
24020 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
24030 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
24040 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
24050 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f   callback has fo
24060 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43  ur arguments: xC
24070 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
24080 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
24090 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
240a0 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  he integer type 
240b0 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20  codes above..** 
240c0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
240d0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
240e0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
240f0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
24100 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75  e.** fourth argu
24110 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
24120 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a  _trace_v2()]..**
24130 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
24140 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
24150 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
24160 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
24170 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
24180 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24190 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  T]] <dt>SQLITE_T
241a0 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a  RACE_STMT</dt>.*
241b0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
241c0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c  _TRACE_STMT call
241d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
241e0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20  when a prepared 
241f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72  statement.** fir
24200 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e  st begins runnin
24210 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61  g and possibly a
24220 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75  t other times du
24230 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63  ring the.** exec
24240 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65  ution of the pre
24250 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
24260 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20   such as at the 
24270 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a  start of each.**
24280 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
24290 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75  ram. ^The P argu
242a0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
242b0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r to the.** [pre
242c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
242d0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e  . ^The X argumen
242e0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
242f0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
24300 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70  .** is the unexp
24310 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f  anded SQL text o
24320 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
24330 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53  tatement or an S
24340 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74  QL comment .** t
24350 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
24360 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  e invocation of 
24370 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65  a trigger.  ^The
24380 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f   callback can co
24390 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d  mpute.** the sam
243a0 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c  e text that woul
243b0 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75  d have been retu
243c0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61  rned by the lega
243d0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  cy [sqlite3_trac
243e0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
243f0 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58  e by using the X
24400 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58   argument when X
24410 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d   begins with "--
24420 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a  " and invoking.*
24430 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  * [sqlite3_expan
24440 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65  ded_sql(P)] othe
24450 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rwise..**.** [[S
24460 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
24470 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ILE]] <dt>SQLITE
24480 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f  _TRACE_PROFILE</
24490 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
244a0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
244b0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f  ILE callback pro
244c0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74  vides approximat
244d0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ely the same.** 
244e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
244f0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
24500 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  e [sqlite3_profi
24510 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a  le()] callback..
24520 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
24530 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
24540 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
24550 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
24560 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
24570 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34  t points to a 64
24580 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69  -bit integer whi
24590 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61  ch is the estima
245a0 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75  ted of.** the nu
245b0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
245c0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70  nd that the prep
245d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
245e0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e  ook to run..** ^
245f0 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  The SQLITE_TRACE
24600 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
24610 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
24620 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
24630 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
24640 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  [[SQLITE_TRACE_R
24650 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OW]] <dt>SQLITE_
24660 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a  TRACE_ROW</dt>.*
24670 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
24680 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62  _TRACE_ROW callb
24690 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
246a0 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72  henever a prepar
246b0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
246c0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67  generates a sing
246d0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  le row of result
246e0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  .  .** ^The P ar
246f0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
24700 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
24710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24720 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
24730 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
24740 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24750 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64  TRACE_CLOSE]] <d
24760 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  t>SQLITE_TRACE_C
24770 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
24780 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
24790 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b  E_CLOSE callback
247a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
247b0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
247c0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
247d0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
247e0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
247f0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
24800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
24810 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65  bject.** and the
24820 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
24830 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  nused..** </dl>.
24840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24850 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20  E_TRACE_STMT    
24860 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20     0x01.#define 
24870 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24880 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65  FILE    0x02.#de
24890 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
248a0 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30  E_ROW        0x0
248b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
248c0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20  _TRACE_CLOSE    
248d0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x08../*.** CA
248e0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
248f0 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44  e Hook.** METHOD
24900 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24910 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
24920 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69  ce_v2(D,M,X,P) i
24930 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
24940 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62  rs a trace callb
24950 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
24960 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62  X against [datab
24970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24980 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74  D, using propert
24990 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20  y mask M.** and 
249a0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
249b0 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61  P.  ^If the X ca
249c0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c  llback is.** NUL
249d0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61  L or if the M ma
249e0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  sk is zero, then
249f0 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61   tracing is disa
24a00 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20  bled.  The.** M 
24a10 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
24a20 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f  be the bitwise O
24a30 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
24a40 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d   of.** zero or m
24a50 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  ore [SQLITE_TRAC
24a60 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  E] constants..**
24a70 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74  .** ^Each call t
24a80 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  o either sqlite3
24a90 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
24aa0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f  te3_trace_v2() o
24ab0 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61  verrides .** (ca
24ac0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72  ncels) any prior
24ad0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
24ae0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
24af0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e  ite3_trace_v2().
24b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61  .**.** ^The X ca
24b10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24b20 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f  d whenever any o
24b30 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65  f the events ide
24b40 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d  ntified by .** m
24b50 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54  ask M occur.  ^T
24b60 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72  he integer retur
24b70 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65  n value from the
24b80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72   callback is cur
24b90 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65  rently.** ignore
24ba0 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d  d, though this m
24bb0 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  ay change in fut
24bc0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43  ure releases.  C
24bd0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65  allback.** imple
24be0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
24bf0 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f  d return zero to
24c00 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63   ensure future c
24c10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
24c20 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
24c30 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24c40 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d   with four argum
24c50 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54  ents: callback(T
24c60 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
24c70 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
24c80 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ne of the [SQLIT
24c90 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73  E_TRACE].** cons
24ca0 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74  tants to indicat
24cb0 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61  e why the callba
24cc0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a  ck was invoked..
24cd0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
24ce0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
24cf0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
24d00 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ter..** The P an
24d10 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
24d20 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
24d30 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
24d40 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on T..**.** The
24d50 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24d60 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
24d70 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70   intended to rep
24d80 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a  lace the legacy.
24d90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
24da0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
24db0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  and [sqlite3_pro
24dc0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66  file()], both of
24dd0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65   which.** are de
24de0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74  precated..*/.int
24df0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24e00 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
24e10 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
24e20 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
24e30 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
24e40 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
24e50 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
24e60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24e70 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
24e80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
24e90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
24ea0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24eb0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
24ec0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
24ed0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
24ee0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
24ef0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
24f00 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
24f10 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
24f20 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
24f30 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
24f40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
24f50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24f60 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
24f70 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
24f80 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
24f90 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
24fa0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
24fb0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
24fc0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
24fd0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
24fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
24ff0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
25000 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
25010 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
25020 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
25030 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
25040 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
25050 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
25060 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
25070 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
25080 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
25090 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
250a0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
250b0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
250c0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
250d0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
250e0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
250f0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
25100 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
25110 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
25120 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
25130 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25140 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
25150 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
25160 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
25170 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
25180 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
25190 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
251a0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
251b0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
251c0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
251d0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
251e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
251f0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
25200 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
25210 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
25220 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
25230 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
25240 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
25250 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
25260 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
25270 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
25280 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
25290 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
252a0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
252b0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
252c0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
252d0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
252e0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
252f0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
25300 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
25310 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
25320 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
25330 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
25340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
25360 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
25370 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
25380 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
25390 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
253a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
253b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
253c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
253d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
253e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
253f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
25400 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
25410 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
25420 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
25430 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
25440 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
25450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25460 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
25470 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
25480 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
25490 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
254a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
254b0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
254c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
254d0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
254e0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
254f0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
25500 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25510 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
25520 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
25530 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
25540 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
25550 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
25560 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
25570 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
25580 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
25590 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
255a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
255b0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
255c0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
255d0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
255e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
255f0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
25600 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
25610 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
25620 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
25630 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
25640 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
25650 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
25660 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
25670 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
25680 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
25690 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
256a0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
256b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
256c0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
256d0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
256e0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
256f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
25700 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
25710 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
25720 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
25730 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
25740 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
25750 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
25760 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
25770 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
25780 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
25790 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
257a0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
257b0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
257c0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
257d0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
257e0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
257f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
25800 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
25810 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
25820 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
25830 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
25840 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
25850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25860 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
25870 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
25880 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
25890 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
258a0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
258b0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
258c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
258d0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
258e0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
258f0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
25900 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
25910 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
25920 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
25930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25940 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
25950 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
25960 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
25970 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
25980 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
25990 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
259a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
259b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
259c0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
259d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
259e0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
259f0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
25a00 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
25a10 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
25a20 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
25a30 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
25a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
25a50 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
25a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
25a70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
25a80 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
25a90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
25aa0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
25ab0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
25ac0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
25ad0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
25ae0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
25af0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
25b00 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25b10 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
25b20 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25b30 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
25b40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
25b50 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
25b60 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
25b70 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25b80 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
25b90 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
25ba0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
25bb0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
25bc0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
25bd0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
25be0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
25bf0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
25c00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
25c10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25c20 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
25c30 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
25c40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25c50 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
25c60 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
25c70 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
25c80 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
25c90 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
25ca0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
25cb0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
25cc0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
25cd0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
25ce0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
25cf0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
25d00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
25d10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
25d20 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
25d30 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
25d40 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
25d50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25d60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25d70 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
25d80 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
25d90 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
25da0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
25db0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
25dc0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
25dd0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
25de0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
25df0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
25e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
25e10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
25e20 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
25e30 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25e40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25e50 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
25e60 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
25e70 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
25e80 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
25e90 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
25ea0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
25eb0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
25ec0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
25ed0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
25ee0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
25ef0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
25f00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
25f10 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
25f20 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25f30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
25f40 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
25f50 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
25f60 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
25f70 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
25f80 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
25f90 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
25fa0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
25fb0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
25fc0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
25fd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
25fe0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
25ff0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
26000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
26010 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
26020 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
26030 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
26040 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
26050 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
26060 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
26070 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
26080 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
26090 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
260a0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
260b0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
260c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
260d0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
260e0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
260f0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
26100 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26110 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
26120 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
26130 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
26140 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
26150 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
26160 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
26170 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
26180 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
26190 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
261a0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
261b0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
261c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
261d0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
261e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
261f0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
26200 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26210 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
26220 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
26230 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
26240 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
26250 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
26260 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
26270 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
26280 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26290 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
262a0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
262b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
262c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
262d0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
262e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
262f0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
26300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
26310 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
26320 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
26330 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
26340 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
26350 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
26360 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
26370 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
26380 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
26390 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
263a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
263b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
263c0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
263d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
263e0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
263f0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
26400 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
26410 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
26420 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
26430 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
26440 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
26450 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
26460 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
26470 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
26480 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
26490 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
264a0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
264b0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
264c0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
264d0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
264e0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
264f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26500 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26510 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
26520 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
26530 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
26540 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
26550 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
26560 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
26570 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
26580 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
26590 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
265a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
265b0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
265c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
265d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
265e0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
265f0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
26600 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
26610 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
26620 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
26630 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
26640 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
26650 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
26660 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
26670 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26680 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
26690 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
266a0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
266b0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
266c0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
266d0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
266e0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
266f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
26700 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
26710 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
26720 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
26730 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
26740 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
26750 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
26760 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
26770 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
26780 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
26790 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
267a0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49  e option..** URI
267b0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
267c0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
267d0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
267e0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
267f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
26800 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
26810 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
26820 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
26830 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
26840 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
26850 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
26860 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
26870 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
26880 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
26890 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
268a0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
268b0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
268c0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
268d0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
268e0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
268f0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
26900 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
26910 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
26920 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
26930 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
26940 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
26950 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
26960 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
26970 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
26980 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
26990 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
269a0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
269b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
269c0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
269d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
269e0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
269f0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
26a00 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
26a10 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
26a20 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
26a30 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
26a40 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
26a50 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
26a60 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
26a70 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
26a80 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
26a90 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
26aa0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
26ab0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
26ac0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
26ad0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
26ae0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
26af0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
26b00 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
26b10 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
26b20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
26b30 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
26b40 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
26b50 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
26b60 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
26b70 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
26b80 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
26b90 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
26ba0 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
26bb0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
26bc0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
26bd0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
26be0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
26bf0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
26c00 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
26c10 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
26c20 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
26c30 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
26c40 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
26c50 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
26c60 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
26c70 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
26c80 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
26c90 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
26ca0 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
26cb0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26cc0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
26cd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
26ce0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
26cf0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
26d00 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
26d10 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
26d20 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
26d30 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
26d40 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
26d50 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
26d60 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
26d70 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
26d80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
26d90 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
26da0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
26db0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
26dc0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
26dd0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
26de0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
26df0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
26e00 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
26e10 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
26e20 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
26e30 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
26e40 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
26e50 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
26e60 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
26e70 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
26e80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26e90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26ea0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
26eb0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
26ec0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
26ed0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
26ee0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
26ef0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
26f00 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
26f10 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
26f20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
26f30 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
26f40 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
26f50 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
26f60 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
26f70 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26f80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
26f90 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
26fa0 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
26fb0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26fc0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
26fd0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
26fe0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
26ff0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
27000 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27010 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
27020 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
27030 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
27040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
27050 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
27060 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
27070 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
27080 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
27090 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
270a0 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
270b0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
270c0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
270d0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
270e0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
270f0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
27100 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
27110 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
27120 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
27130 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
27140 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
27150 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
27160 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
27170 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
27180 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
27190 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
271a0 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
271b0 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
271c0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
271d0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
271e0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
271f0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
27200 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
27210 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
27220 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
27230 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
27240 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
27250 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
27260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27270 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
27280 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
27290 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
272a0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
272b0 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
272c0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
272d0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
272e0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
272f0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
27300 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
27310 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
27320 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
27330 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
27340 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
27350 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
27360 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
27370 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
27380 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
27390 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
273a0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
273b0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
273c0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
273d0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
273e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
273f0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
27400 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
27410 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
27420 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
27430 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
27440 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
27450 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
27460 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
27470 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
27480 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
27490 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
274a0 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
274b0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
274c0 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
274d0 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
274e0 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
274f0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
27500 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
27510 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
27520 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
27530 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
27540 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
27550 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
27560 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
27570 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
27580 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
27590 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
275a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
275b0 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
275c0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
275d0 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
275e0 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
275f0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
27600 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
27610 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
27620 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
27630 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
27640 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
27650 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
27660 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
27670 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
27680 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
27690 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
276a0 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
276b0 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
276c0 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
276d0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
276e0 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
276f0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
27700 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
27710 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
27720 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
27730 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
27740 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
27750 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
27760 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
27770 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
27780 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
27790 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
277a0 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
277b0 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
277c0 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
277d0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
277e0 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
277f0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
27800 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
27810 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
27820 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
27830 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
27840 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
27850 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
27860 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
27870 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
27880 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
27890 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
278a0 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
278b0 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
278c0 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
278d0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
278e0 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
278f0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
27900 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
27910 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
27920 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
27930 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
27940 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
27950 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
27960 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
27970 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
27980 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
27990 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
279a0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
279b0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
279c0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
279d0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
279e0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
279f0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
27a00 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
27a10 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
27a20 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
27a30 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
27a40 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
27a50 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
27a60 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
27a70 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27a80 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
27a90 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
27aa0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
27ab0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
27ac0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
27ad0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
27ae0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
27af0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
27b00 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
27b10 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
27b20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27b30 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
27b40 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
27b50 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27b60 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
27b70 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
27b80 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
27b90 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
27ba0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
27bb0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
27bc0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
27bd0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
27be0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
27bf0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
27c00 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
27c10 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
27c20 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
27c30 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
27c40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27c50 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
27c60 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
27c70 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27c80 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
27c90 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
27ca0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
27cb0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
27cc0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
27cd0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
27ce0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
27cf0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
27d00 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
27d10 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
27d20 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
27d30 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
27d40 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
27d50 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
27d60 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
27d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
27d80 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
27d90 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
27da0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
27db0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
27dc0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
27dd0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
27de0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
27df0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
27e00 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
27e10 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
27e20 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27e30 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
27e40 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
27e50 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27e60 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
27e70 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
27e80 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
27e90 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
27ea0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
27eb0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
27ec0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
27ed0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
27ee0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
27ef0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
27f00 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
27f10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27f20 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
27f30 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
27f40 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
27f50 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
27f60 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
27f70 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
27f80 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
27f90 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
27fa0 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
27fb0 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
27fc0 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
27fd0 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
27fe0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
27ff0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
28000 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
28010 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
28020 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
28030 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
28040 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
28050 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
28060 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
28070 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
28080 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
28090 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
280a0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
280b0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
280c0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
280d0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
280e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
280f0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
28100 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
28110 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
28120 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
28130 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
28140 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
28150 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
28160 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
28170 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
28180 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
28190 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
281a0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
281b0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
281c0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
281d0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
281e0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
281f0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
28200 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
28210 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
28220 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
28230 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
28240 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
28250 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
28260 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
28270 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
28280 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
28290 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
282a0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
282b0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
282c0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
282d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
282e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
282f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
28300 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
28310 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
28320 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
28330 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
28340 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
28350 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
28360 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
28370 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
28380 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
28390 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
283a0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
283b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
283c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
283d0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
283e0 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
283f0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
28400 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
28410 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
28420 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
28430 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
28440 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
28450 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
28460 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
28470 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
28480 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
28490 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
284a0 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
284b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
284c0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
284d0 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
284e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
284f0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
28500 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
28510 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
28520 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
28530 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
28540 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
28550 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
28560 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28570 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
28580 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
28590 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
285a0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
285b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
285c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
285d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
285e0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
285f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
28600 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
28610 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
28620 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
28630 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
28640 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
28650 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
28660 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
28670 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
28680 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
28690 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
286a0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
286b0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
286c0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
286d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
286e0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
286f0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
28700 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
28710 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
28720 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
28730 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
28740 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
28750 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
28760 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
28770 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
28780 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
28790 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
287a0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
287b0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
287c0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
287d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
287e0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
287f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
28800 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
28810 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
28820 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
28830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28840 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
28850 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
28860 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
28870 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
28880 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
28890 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
288a0 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
288b0 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
288c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
288d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
288e0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
288f0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
28900 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
28910 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
28920 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
28930 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
28940 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
28950 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
28960 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
28970 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
28980 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
28990 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
289a0 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
289b0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
289c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
289d0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
289e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
289f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
28a00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28a10 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28a20 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
28a30 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
28a40 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
28a50 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
28a60 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
28a70 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
28a80 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
28a90 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
28aa0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28ab0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
28ac0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
28ad0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
28ae0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
28af0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
28b00 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
28b10 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
28b20 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
28b30 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
28b40 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
28b50 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
28b60 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28b70 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
28b80 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
28b90 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
28ba0 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
28bb0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
28bc0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
28bd0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
28be0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
28bf0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
28c00 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
28c10 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
28c20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
28c30 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
28c40 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
28c50 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
28c60 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
28c70 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
28c80 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28c90 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
28ca0 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
28cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
28cc0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
28cd0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
28ce0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
28cf0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
28d00 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
28d10 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
28d20 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
28d30 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
28d40 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
28d50 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
28d60 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
28d70 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
28d80 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
28d90 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
28da0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28db0 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
28dc0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
28dd0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
28de0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
28df0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28e00 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
28e10 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
28e20 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
28e30 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
28e40 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
28e50 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
28e60 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
28e70 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
28e80 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
28e90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
28ea0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
28eb0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28ec0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
28ed0 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
28ee0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
28ef0 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
28f00 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
28f10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
28f20 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
28f30 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
28f40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
28f50 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
28f60 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
28f70 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
28f80 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
28f90 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
28fa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
28fb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
28fc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28fd0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
28fe0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
28ff0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
29000 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
29010 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
29020 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
29030 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
29040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29050 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
29060 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
29070 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
29080 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
29090 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
290a0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
290b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
290c0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
290d0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
290e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
290f0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
29100 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
29110 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29120 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
29130 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
29140 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
29150 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
29160 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
29170 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
29180 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
29190 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
291a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
291b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
291c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
291d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
291e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
291f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29200 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
29210 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
29220 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
29230 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
29240 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
29250 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
29260 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
29270 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
29280 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
29290 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
292a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
292b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
292c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
292d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
292e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
292f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
29300 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
29310 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
29320 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
29330 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
29340 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
29350 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
29360 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
29370 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
29380 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
29390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
293a0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
293b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
293c0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
293d0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
293e0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
293f0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
29400 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
29410 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
29420 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
29430 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
29440 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
29450 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
29460 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
29470 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
29480 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
29490 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
294a0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
294b0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
294c0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
294d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
294e0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
294f0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
29500 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
29510 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
29520 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
29530 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
29540 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
29550 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
29560 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
29570 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
29580 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
29590 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
295a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
295b0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
295c0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
295d0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
295e0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
295f0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
29600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
29610 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
29620 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
29630 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
29640 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
29650 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
29660 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
29670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
29680 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
29690 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
296a0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
296b0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
296c0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
296d0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
296e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
296f0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
29700 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
29710 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
29720 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
29730 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
29740 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
29750 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
29760 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
29770 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
29780 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
29790 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
297a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
297b0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
297c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
297d0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
297e0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
297f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29800 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
29810 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29820 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
29830 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
29840 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
29850 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
29860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
29870 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
29880 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
29890 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
298a0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
298b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
298c0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
298d0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
298e0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
298f0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
29900 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
29910 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
29920 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
29930 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
29940 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
29950 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
29960 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
29970 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
29980 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
29990 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
299a0 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
299b0 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
299c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
299d0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
299e0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
299f0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
29a00 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
29a10 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
29a20 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
29a30 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
29a40 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
29a50 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
29a60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a70 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
29a80 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
29a90 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
29aa0 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
29ab0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29ac0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
29ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29ae0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
29af0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
29b00 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
29b10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29b20 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
29b30 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
29b40 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
29b50 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29b60 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
29b70 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
29b80 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
29b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29ba0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
29bb0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
29bc0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
29bd0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
29be0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
29bf0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
29c00 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
29c10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
29c20 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
29c30 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
29c40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
29c50 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
29c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29c70 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
29c80 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
29c90 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
29ca0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
29cb0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
29cc0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
29cd0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
29ce0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
29cf0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
29d00 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
29d10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
29d20 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
29d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
29d40 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
29d50 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
29d60 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
29d70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
29d80 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
29d90 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
29da0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
29db0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
29dc0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
29dd0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
29de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29df0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
29e00 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
29e10 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
29e20 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
29e30 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
29e40 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
29e50 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
29e60 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
29e70 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
29e80 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
29e90 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
29ea0 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
29eb0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
29ec0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
29ed0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
29ee0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
29ef0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
29f00 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
29f10 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
29f20 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
29f30 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
29f40 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
29f50 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
29f60 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
29f70 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
29f80 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
29f90 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
29fa0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
29fb0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
29fc0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
29fd0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
29fe0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
29ff0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
2a000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
2a010 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
2a020 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
2a030 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
2a040 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
2a050 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
2a060 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
2a070 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
2a080 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
2a090 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
2a0a0 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
2a0b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2a0c0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
2a0d0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
2a0e0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
2a0f0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
2a100 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
2a110 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
2a120 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
2a130 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
2a140 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
2a150 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
2a160 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
2a170 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2a180 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
2a190 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
2a1a0 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
2a1b0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
2a1c0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
2a1d0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
2a1e0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
2a1f0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
2a200 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
2a210 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
2a220 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
2a230 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
2a240 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
2a250 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
2a260 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
2a270 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
2a280 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
2a290 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
2a2a0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
2a2b0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
2a2c0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
2a2d0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
2a2e0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
2a2f0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
2a300 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
2a310 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
2a320 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
2a330 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
2a340 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
2a350 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
2a360 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
2a370 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
2a380 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2a390 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
2a3a0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
2a3b0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
2a3c0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2a3d0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
2a3e0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
2a3f0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
2a400 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
2a410 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2a420 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
2a430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
2a440 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
2a450 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
2a460 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2a470 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
2a480 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
2a490 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
2a4a0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
2a4b0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
2a4c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2a4d0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2a4e0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
2a4f0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
2a500 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
2a510 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2a520 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
2a530 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
2a540 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
2a550 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
2a560 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
2a570 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
2a580 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2a590 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
2a5a0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
2a5b0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
2a5c0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2a5d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2a5e0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2a5f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2a600 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2a610 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
2a620 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
2a630 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
2a640 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
2a650 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a660 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2a670 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2a680 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2a690 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a6a0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2a6b0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
2a6c0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
2a6d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a6e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2a6f0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
2a700 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
2a710 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a720 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a730 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
2a740 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
2a750 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
2a760 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2a770 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
2a780 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2a790 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
2a7a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
2a7b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
2a7c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
2a7d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a7e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a7f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2a800 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a810 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a820 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2a830 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
2a840 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
2a850 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
2a860 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a870 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a880 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2a890 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2a8a0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
2a8b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a8c0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2a8d0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
2a8e0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
2a8f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a900 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2a910 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
2a920 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
2a930 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a940 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a950 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
2a960 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
2a970 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
2a980 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2a990 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2a9a0 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
2a9b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2a9c0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
2a9d0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
2a9e0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
2a9f0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
2aa00 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
2aa10 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
2aa20 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
2aa30 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
2aa40 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
2aa50 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2aa60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2aa70 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
2aa80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
2aa90 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
2aaa0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2aab0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
2aac0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
2aad0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
2aae0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2aaf0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
2ab00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2ab10 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
2ab20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2ab30 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
2ab40 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
2ab50 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
2ab60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
2ab70 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2ab80 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
2ab90 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2aba0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2abb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2abc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
2abd0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
2abe0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
2abf0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
2ac00 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
2ac10 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2ac20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2ac30 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2ac40 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2ac50 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ac60 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
2ac70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2ac80 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
2ac90 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
2aca0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
2acb0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
2acc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2acd0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
2ace0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
2acf0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
2ad00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ad10 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
2ad20 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
2ad30 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
2ad40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2ad50 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2ad60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2ad70 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2ad80 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
2ad90 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2ada0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
2adb0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
2adc0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
2add0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ade0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
2adf0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
2ae00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2ae10 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
2ae20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ae30 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
2ae40 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2ae50 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2ae60 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2ae70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2ae80 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
2ae90 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2aea0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2aeb0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2aec0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2aed0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2aee0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
2aef0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
2af00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
2af10 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
2af20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
2af30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
2af40 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
2af50 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
2af60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2af70 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
2af80 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
2af90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2afa0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2afb0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
2afc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2afd0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2afe0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
2aff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2b000 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2b010 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2b020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2b030 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2b040 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2b050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b060 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a   Prepare Flags.*
2b070 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2b080 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2b090 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
2b0a0 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
2b0b0 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22  o.** "prepFlags"
2b0c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2b0d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2b0e0 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20  re_v3()] and.** 
2b0f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b100 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61  16_v3()] interfa
2b110 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66  ces..**.** New f
2b120 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65  lags may be adde
2b130 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2b140 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
2b150 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2b160 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2b170 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64  ERSISTENT]] ^(<d
2b180 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2b190 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e  _PERSISTENT</dt>
2b1a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2b1b0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2b1c0 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20  STENT flag is a 
2b1d0 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72  hint to the quer
2b1e0 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61  y planner.** tha
2b1f0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2b200 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2b210 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20   retained for a 
2b220 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a  long time and.**
2b230 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64   probably reused
2b240 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e   many times.)^ ^
2b250 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61  Without this fla
2b260 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  g, [sqlite3_prep
2b270 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64  are_v3()].** and
2b280 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b290 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65  e16_v3()] assume
2b2a0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2b2b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2b2c0 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75  l .** be used ju
2b2d0 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f  st once or at mo
2b2e0 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61  st a few times a
2b2f0 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  nd then destroye
2b300 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2b310 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b320 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e  relatively soon.
2b330 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   The current imp
2b340 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73  lementation acts
2b350 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  .** on this hint
2b360 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65   by avoiding the
2b370 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69   use of [lookasi
2b380 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73  de memory] so as
2b390 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65   not to.** deple
2b3a0 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73  te the limited s
2b3b0 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  tore of lookasid
2b3c0 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65  e memory. Future
2b3d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20   versions of.** 
2b3e0 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f  SQLite may act o
2b3f0 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66  n this hint diff
2b400 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c  erently..** </dl
2b410 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2b420 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2b430 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20  ISTENT          
2b440 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20      0x01../*.** 
2b450 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
2b460 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
2b470 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
2b480 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
2b490 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
2b4a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2b4b0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
2b4c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b4d0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
2b4e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74  QL statement, it
2b4f0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2b500 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2b510 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2b520 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2b530 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2b540 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77    Or, in other w
2b550 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74  ords, these rout
2b560 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73  ines.** are cons
2b570 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65  tructors for the
2b580 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b590 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ment] object..**
2b5a0 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 65  .** The preferre
2b5b0 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65  d routine to use
2b5c0 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   is [sqlite3_pre
2b5d0 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65  pare_v2()].  The
2b5e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b5f0 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63  pare()] interfac
2b600 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  e is legacy and 
2b610 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
2b620 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  d..** [sqlite3_p
2b630 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73  repare_v3()] has
2b640 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 46   an extra "prepF
2b650 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61  lags" option tha
2b660 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72  t is used.** for
2b670 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65   special purpose
2b680 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65  s..**.** The use
2b690 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e   of the UTF-8 in
2b6a0 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65 66  terfaces is pref
2b6b0 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65  erred, as SQLite
2b6c0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f   currently.** do
2b6d0 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75  es all parsing u
2b6e0 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65  sing UTF-8.  The
2b6f0 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2b700 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
2b710 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65  ** as a convenie
2b720 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36  nce.  The UTF-16
2b730 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
2b740 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74   by converting t
2b750 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74  he.** input text
2b760 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65   into UTF-8, the
2b770 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  n invoking the c
2b780 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46  orresponding UTF
2b790 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  -8 interface..**
2b7a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2b7b0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
2b7c0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2b7d0 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
2b7e0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
2b7f0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
2b800 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
2b810 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2b820 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
2b830 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2b840 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
2b850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2b860 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
2b870 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
2b880 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2b890 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
2b8a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
2b8b0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
2b8c0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
2b8d0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
2b8e0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
2b8f0 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74  prepare(), sqlit
2b900 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2b910 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2b920 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20  prepare_v3().** 
2b930 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
2b940 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
2b950 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 73  3_prepare16(), s
2b960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b970 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b990 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e  v3() use UTF-16.
2b9a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2b9b0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2b9c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2b9d0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2b9e0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2b9f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2ba00 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2ba10 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2ba20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ba30 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2ba40 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2ba50 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2ba60 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2ba70 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2ba80 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2ba90 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2baa0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2bab0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2bac0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2bad0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2bae0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2baf0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2bb00 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2bb10 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2bb20 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2bb30 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2bb40 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2bb50 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2bb60 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2bb70 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2bb80 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2bb90 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2bba0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2bbb0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2bbc0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2bbd0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2bbe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2bbf0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2bc00 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2bc10 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2bc20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2bc30 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2bc40 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2bc50 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2bc60 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2bc70 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2bc80 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2bc90 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2bca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bcb0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2bcc0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2bcd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2bce0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2bcf0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2bd00 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2bd10 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2bd20 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2bd30 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2bd40 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2bd50 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2bd60 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2bd70 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2bd80 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2bd90 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2bda0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2bdb0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2bdc0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2bdd0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2bde0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bdf0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2be00 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2be10 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2be20 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2be30 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2be40 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2be50 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2be60 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2be70 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2be80 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2be90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2bea0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2beb0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2bec0 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33  re_v2(), sqlite3
2bed0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73  _prepare_v3(), s
2bee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bef0 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2bf00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bf10 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v3() interfaces 
2bf20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  are recommended 
2bf30 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2bf40 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64  rams..** The old
2bf50 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  er interfaces (s
2bf60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2bf70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2bf80 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65  pare16()).** are
2bf90 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
2bfa0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2bfb0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
2bfc0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
2bfd0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
2bfe0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "vX" interfaces,
2bff0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2c000 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
2c010 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
2c020 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2c030 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
2c040 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2c050 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
2c060 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
2c070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2c080 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
2c090 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
2c0a0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
2c0b0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
2c0c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
2c0d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
2c0e0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
2c0f0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
2c100 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
2c110 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
2c120 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
2c130 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c140 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
2c150 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
2c160 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
2c170 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
2c180 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
2c190 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
2c1a0 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
2c1b0 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
2c1c0 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
2c1d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
2c1e0 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
2c1f0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
2c200 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2c210 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
2c220 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
2c230 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2c240 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
2c250 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
2c260 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
2c270 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2c280 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
2c290 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
2c2a0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
2c2b0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
2c2c0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
2c2d0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
2c2e0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
2c2f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
2c300 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
2c310 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
2c320 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
2c330 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
2c340 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2c350 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
2c360 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
2c370 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
2c380 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
2c390 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2c3a0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
2c3b0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
2c3c0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
2c3d0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
2c3e0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2c3f0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
2c400 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
2c410 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
2c420 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
2c430 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
2c440 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
2c450 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
2c460 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
2c470 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
2c480 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
2c490 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
2c4a0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2c4b0 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
2c4c0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
2c4d0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
2c4e0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
2c4f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c500 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
2c510 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
2c520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2c530 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
2c540 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
2c550 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
2c560 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2c570 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
2c580 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
2c590 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2c5a0 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
2c5b0 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
2c5c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c5d0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
2c5e0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
2c5f0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
2c600 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
2c610 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
2c620 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
2c630 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
2c640 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
2c650 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
2c660 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
2c670 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
2c680 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
2c690 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70  <p>^sqlite3_prep
2c6a0 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73  are_v3() differs
2c6b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72   from sqlite3_pr
2c6c0 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20  epare_v2() only 
2c6d0 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65  in having.** the
2c6e0 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73   extra prepFlags
2c6f0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
2c700 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79  h is a bit array
2c710 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a   consisting of z
2c720 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f  ero or.** more o
2c730 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52  f the [SQLITE_PR
2c740 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2c750 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  |SQLITE_PREPARE_
2c760 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a  *] flags.  ^The.
2c770 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2c780 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  re_v2() interfac
2c790 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  e works exactly 
2c7a0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
2c7b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c7c0 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20  3() with a zero 
2c7d0 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2c7e0 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
2c7f0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
2c800 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c810 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c820 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c830 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2c840 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c850 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2c860 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2c870 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2c880 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2c890 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2c8a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2c8b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2c8c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2c8d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2c8e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2c8f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c900 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c910 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c920 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2c930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c940 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2c950 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c960 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c970 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c980 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c990 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c9a0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c9b0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c9c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c9d0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c9e0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c9f0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ca00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ca10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ca20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ca30 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2ca40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ca50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ca60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ca70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2ca80 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74  pare_v3(.  sqlit
2ca90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2caa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2cab0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cac0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2cad0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2cae0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2caf0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2cb00 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2cb10 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2cb20 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2cb30 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65  es. */.  unsigne
2cb40 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c  d int prepFlags,
2cb50 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65   /* Zero or more
2cb60 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2cb70 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69   flags */.  sqli
2cb80 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2cb90 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2cba0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2cbb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2cbc0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2cbd0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2cbe0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2cbf0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2cc00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2cc10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2cc20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2cc30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2cc40 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2cc50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2cc60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2cc70 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2cc80 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2cc90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2cca0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2ccb0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2ccc0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2ccd0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2cce0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2ccf0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2cd00 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2cd10 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2cd20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2cd30 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2cd40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2cd50 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
2cd60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2cd70 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2cd80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2cd90 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2cda0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2cdb0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2cdc0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2cdd0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2cde0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2cdf0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2ce00 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2ce10 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ce20 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2ce30 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ce40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2ce50 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2ce60 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2ce70 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ce80 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2ce90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2cea0 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2ceb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2cec0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ced0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2cee0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2cf00 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2cf10 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2cf20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2cf30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2cf40 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2cf50 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2cf60 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2cf70 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2cf80 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2cf90 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2cfa0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2cfb0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2cfc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cfd0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2cfe0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2cff0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2d000 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2d010 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2d020 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2d030 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2d040 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d050 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2d060 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  e sqlite3_sql(P)
2d070 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d080 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d090 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54  a copy of the UT
2d0a0 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  F-8.** SQL text 
2d0b0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b  used to create [
2d0c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d0d0 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a  nt] P if P was.*
2d0e0 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  * created by [sq
2d0f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d100 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
2d110 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20  epare_v3()],.** 
2d120 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d130 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71  16_v2()], or [sq
2d140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d150 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v3()]..** ^The s
2d160 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d170 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2d180 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d190 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2d1a0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2d1b0 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2d1c0 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2d1d0 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2d1e0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2d1f0 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2d200 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d210 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2d220 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2d230 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2d240 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2d250 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2d260 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2d270 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2d280 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2d290 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2d2a0 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2d2b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2d2c0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2d2d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2d2e0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2d2f0 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2d300 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d310 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2d320 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2d330 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2d340 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2d350 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2d360 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2d370 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2d380 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2d390 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2d3a0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2d3b0 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2d3c0 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2d3d0 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2d3e0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2d3f0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2d400 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2d410 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2d420 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2d430 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2d440 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2d450 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2d460 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2d470 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2d480 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2d490 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2d4a0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2d4b0 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2d4c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2d4d0 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2d4e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2d4f0 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2d500 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2d510 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2d520 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2d530 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2d540 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2d550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d560 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2d570 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2d580 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d590 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d5a0 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2d5b0 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2d5c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d5d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2d5e0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2d5f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2d600 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2d610 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2d620 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2d630 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2d640 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2d650 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2d660 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d670 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2d680 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d690 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2d6a0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2d6b0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2d6c0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2d6d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2d6e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2d6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d700 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2d710 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2d720 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2d730 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2d740 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d750 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2d760 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2d770 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2d780 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2d790 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2d7a0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2d7b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2d7c0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2d7d0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2d7e0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2d7f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2d800 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2d810 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2d820 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2d830 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2d840 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2d850 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2d860 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2d870 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2d880 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2d890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2d8a0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2d8b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2d8c0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2d8d0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2d8e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2d8f0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2d900 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2d910 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2d920 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2d930 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2d940 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2d950 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2d960 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2d970 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2d980 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2d990 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d9a0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2d9b0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2d9c0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2d9d0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2d9e0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2d9f0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2da00 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2da10 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2da20 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2da30 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2da40 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2da50 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2da60 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2da70 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2da80 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2da90 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2daa0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2dab0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2dac0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2dad0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2dae0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2daf0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2db00 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2db10 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2db20 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2db30 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2db40 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2db50 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2db60 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2db70 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2db80 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2db90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dba0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2dbb0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2dbc0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2dbd0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2dbe0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2dbf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dc00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2dc10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2dc20 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2dc30 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2dc40 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2dc50 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2dc60 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2dc70 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2dc80 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2dc90 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2dca0 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2dcb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2dcc0 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2dcd0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2dce0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2dcf0 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2dd00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2dd10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2dd20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2dd30 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2dd40 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2dd50 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2dd60 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2dd70 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2dd80 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2dd90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2dda0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2ddb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ddc0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2ddd0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2dde0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ddf0 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2de00 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2de10 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2de20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2de30 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2de40 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2de50 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2de60 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2de70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2de80 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2de90 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2dea0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2deb0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2dec0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2ded0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2dee0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2def0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2df00 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2df10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2df20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2df30 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2df40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2df50 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2df60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2df70 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2df80 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2df90 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2dfa0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2dfb0 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2dfc0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2dfd0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2dfe0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2dff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2e000 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e010 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2e020 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2e030 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2e040 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2e050 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2e060 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2e070 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2e080 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2e090 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2e0a0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2e0b0 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2e0c0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2e0d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2e0e0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2e0f0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2e100 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2e110 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2e120 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2e130 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2e140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2e150 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2e160 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2e170 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2e180 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e190 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2e1a0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2e1b0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2e1c0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2e1d0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2e1e0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2e1f0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2e200 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2e210 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2e220 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2e230 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2e240 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2e250 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2e260 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2e270 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2e280 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2e290 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2e2a0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2e2b0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2e2c0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2e2d0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2e2e0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2e2f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2e300 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2e310 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2e320 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2e330 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2e340 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e350 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2e360 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2e370 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2e380 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2e390 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2e3a0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2e3b0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2e3c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2e3d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2e3e0 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2e3f0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2e400 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2e410 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2e420 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e430 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2e440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e450 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2e460 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2e470 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2e480 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2e490 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2e4a0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2e4b0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2e4c0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2e4d0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e4e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e4f0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2e500 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2e510 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e520 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e530 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2e540 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2e550 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2e560 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2e570 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2e580 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2e590 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2e5a0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2e5b0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2e5c0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2e5d0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2e5e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2e5f0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2e600 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2e610 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2e620 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2e630 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2e640 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2e650 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2e660 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e670 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2e680 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2e690 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2e6a0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2e6b0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2e6c0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2e6d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2e6e0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2e6f0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2e700 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2e710 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e720 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e730 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e740 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2e750 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2e760 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2e770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2e780 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2e790 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2e7a0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2e7b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2e7c0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2e7d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e7e0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2e7f0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2e800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e810 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e820 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e830 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2e840 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2e850 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2e860 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e870 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2e880 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74  used as argument
2e890 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2e8a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2e8b0 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  , [sqlite3_bind_
2e8c0 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  value()], and.**
2e8d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e8e0 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  dup()]..** The [
2e8f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2e900 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2e910 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2e920 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2e930 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2e940 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e950 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2e960 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e970 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
2e980 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2e990 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2e9a0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2e9b0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2e9c0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2e9d0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2e9e0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2e9f0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2ea00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2ea10 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2ea20 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2ea30 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2ea40 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2ea50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2ea60 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2ea70 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2ea80 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2ea90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2eaa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2eab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2eac0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2ead0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2eae0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2eaf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2eb00 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2eb10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2eb20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2eb30 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2eb40 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2eb50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2eb60 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2eb70 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2eb80 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2eb90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2eba0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2ebb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2ebc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2ebd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2ebe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ebf0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2ec00 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2ec10 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2ec20 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2ec30 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2ec40 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2ec50 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2ec60 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2ec70 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2ec80 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2ec90 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2eca0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ecb0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2ecc0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ecd0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2ece0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ecf0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2ed00 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2ed10 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2ed20 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2ed30 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2ed40 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2ed50 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2ed60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2ed70 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2ed80 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2ed90 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2eda0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2edb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2edc0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2edd0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2ede0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2edf0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2ee00 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2ee10 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2ee20 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2ee30 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2ee40 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2ee50 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2ee60 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2ee70 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2ee80 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2ee90 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2eea0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2eeb0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2eec0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2eed0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2eee0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2eef0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ef00 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2ef10 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2ef20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2ef30 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2ef40 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2ef50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ef60 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2ef70 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2ef80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2ef90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2efa0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2efb0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2efc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2efd0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2efe0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2eff0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2f000 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2f010 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2f020 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2f030 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2f040 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2f050 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2f060 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2f070 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2f080 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2f090 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2f0a0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2f0b0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2f0c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2f0d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2f0e0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2f0f0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2f100 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2f110 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2f120 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2f130 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2f140 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2f150 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2f160 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2f170 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2f180 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2f190 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2f1a0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2f1b0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2f1c0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2f1d0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2f1e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2f1f0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2f200 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f210 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2f220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f230 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2f240 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2f250 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2f260 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2f270 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2f280 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2f290 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2f2a0 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2f2b0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2f2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2f2d0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2f2e0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2f2f0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2f300 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2f310 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2f320 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2f330 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2f340 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2f350 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2f360 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2f370 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2f380 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2f390 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2f3a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f3b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2f3c0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2f3d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2f3e0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2f3f0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2f400 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2f410 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2f420 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2f430 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2f440 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2f450 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2f460 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2f470 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2f480 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2f490 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2f4a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2f4b0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2f4c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f4d0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2f4e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f4f0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2f500 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2f510 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2f520 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2f530 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2f540 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2f550 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2f560 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2f570 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2f580 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2f590 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2f5a0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2f5b0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2f5c0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2f5d0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2f5e0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2f5f0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2f600 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2f610 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2f620 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2f630 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2f640 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2f650 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2f660 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2f670 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2f680 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2f690 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f6a0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2f6b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2f6c0 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2f6d0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2f6e0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2f6f0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2f700 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2f710 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2f720 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2f730 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2f740 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f750 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2f760 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2f770 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2f780 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2f790 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2f7a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2f7b0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2f7c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2f7d0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2f7e0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2f7f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2f800 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2f810 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2f820 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2f830 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2f840 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2f850 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f860 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2f870 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2f880 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2f890 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2f8a0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2f8b0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2f8c0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2f8d0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2f8e0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f8f0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2f900 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2f910 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2f920 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2f930 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2f940 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2f950 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2f960 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2f970 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2f980 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2f990 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2f9a0 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2f9b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f9c0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2f9d0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2f9e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f9f0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2fa00 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2fa10 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2fa20 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2fa30 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2fa40 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2fa50 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2fa60 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2fa70 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2fa80 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2fa90 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2faa0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2fab0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2fac0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2fad0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2fae0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2faf0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2fb00 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2fb10 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2fb20 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2fb30 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2fb40 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2fb50 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2fb60 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2fb70 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2fb80 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2fb90 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2fba0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2fbb0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2fbc0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2fbd0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2fbe0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2fbf0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2fc00 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2fc10 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2fc20 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2fc30 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2fc40 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2fc50 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2fc60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2fc70 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50  nd_pointer(S,I,P
2fc80 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61  ,T,D) routine ca
2fc90 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61  uses the I-th pa
2fca0 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70  rameter in.** [p
2fcb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fcc0 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20  t] S to have an 
2fcd0 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c  SQL value of NUL
2fce0 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62  L, but to also b
2fcf0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
2fd00 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72  with the pointer
2fd10 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e   P of type T.  ^
2fd20 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  D is either a NU
2fd30 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a  LL pointer or.**
2fd40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2fd50 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
2fd60 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69  ion for P. ^SQLi
2fd70 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2fd80 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  he.** destructor
2fd90 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2fda0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77   argument of P w
2fdb0 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68  hen it is finish
2fdc0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20  ed using.** P.  
2fdd0 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20  The T parameter 
2fde0 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74  should be a stat
2fdf0 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65  ic string, prefe
2fe00 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a  rably a string.*
2fe10 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73  * literal. The s
2fe20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2fe30 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ter() routine is
2fe40 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
2fe50 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67  [pointer passing
2fe60 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65   interface] adde
2fe70 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32  d for SQLite 3.2
2fe80 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  0.0..**.** ^If a
2fe90 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2fea0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2feb0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2fec0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2fed0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2fee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fef0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2ff00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ff10 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2ff20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ff30 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2ff40 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2ff50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ff60 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2ff70 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2ff80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ff90 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2ffa0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2ffb0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2ffc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ffd0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2ffe0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2fff0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
30000 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
30010 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
30020 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
30030 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
30040 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
30050 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
30060 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
30070 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
30080 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
30090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
300a0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
300b0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
300c0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
300d0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
300e0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
300f0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
30100 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
30110 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
30120 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
30130 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
30140 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
30150 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
30160 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
30170 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
30180 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
30190 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
301a0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
301b0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
301c0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
301d0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
301e0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
301f0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
30200 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
30210 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
30220 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
30230 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30240 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30250 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30260 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30270 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
30280 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30290 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
302a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
302b0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
302c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
302d0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
302e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
302f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
30300 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
30310 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30320 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
30330 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
30340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
30350 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30360 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30370 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
30380 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
30390 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
303a0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
303b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
303c0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
303d0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
303e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
303f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
30400 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30410 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
30420 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
30430 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30440 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
30450 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
30460 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
30470 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30480 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
30490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
304a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
304b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
304c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
304d0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
304e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
304f0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
30500 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
30510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30520 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
30530 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
30540 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
30550 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
30560 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
30570 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
30580 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
30590 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
305a0 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  pointer(sqlite3_
305b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  stmt*, int, void
305c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76  *, const char*,v
305d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
305e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
305f0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
30600 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
30610 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
30620 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
30630 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30640 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
30650 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
30660 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
30670 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
30680 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30690 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
306a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
306b0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
306c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
306d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
306e0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
306f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
30700 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
30710 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
30720 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
30730 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
30740 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
30750 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
30760 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
30770 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
30780 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30790 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
307a0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
307b0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
307c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
307d0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
307e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
307f0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
30800 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
30810 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
30820 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
30830 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
30840 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
30850 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
30860 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
30870 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
30880 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
30890 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
308a0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
308b0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
308c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
308d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
308e0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
308f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30900 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30910 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
30920 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30930 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
30940 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30950 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30960 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30970 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30980 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
30990 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
309a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
309b0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
309c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
309d0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
309e0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
309f0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
30a00 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
30a10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
30a20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30a30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
30a40 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
30a50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
30a60 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30a70 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30a80 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
30a90 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
30aa0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
30ab0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
30ac0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
30ad0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
30ae0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
30af0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
30b00 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
30b10 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
30b20 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
30b30 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
30b40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
30b50 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
30b60 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
30b70 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
30b80 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
30b90 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
30ba0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
30bb0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
30bc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30bd0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
30be0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
30bf0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
30c00 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
30c10 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
30c20 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
30c30 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
30c40 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
30c50 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
30c60 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
30c70 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
30c80 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
30c90 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
30ca0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
30cb0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
30cc0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
30cd0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
30ce0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
30cf0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
30d00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
30d10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30d20 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
30d30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30d40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30d50 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30d70 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30d80 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
30d90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30da0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
30db0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30dc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30dd0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
30de0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
30df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
30e00 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
30e10 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
30e20 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
30e30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30e40 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
30e50 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
30e60 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
30e70 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
30e80 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
30e90 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
30ea0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
30eb0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
30ec0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
30ed0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
30ee0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
30ef0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
30f00 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
30f10 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
30f20 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
30f30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
30f40 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
30f50 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
30f60 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
30f70 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
30f80 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
30f90 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
30fa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30fb0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
30fc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30fd0 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
30fe0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30ff0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
31000 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
31010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31020 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
31030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
31040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
31050 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
31060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31070 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
31080 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
31090 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
310a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
310b0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
310c0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
310d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
310e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
310f0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
31100 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
31110 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
31120 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
31130 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
31140 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
31150 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
31160 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
31170 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31180 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
31190 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
311a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
311b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
311c0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
311d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
311e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
311f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
31200 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
31210 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
31220 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31230 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
31240 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
31250 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
31260 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
31270 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
31280 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31290 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
312a0 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
312b0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
312c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
312d0 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
312e0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
312f0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
31300 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
31310 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
31320 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31330 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
31340 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
31350 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
31360 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
31370 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
31380 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
31390 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
313a0 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
313b0 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
313c0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
313d0 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
313e0 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
313f0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
31400 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
31410 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
31420 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
31430 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
31440 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31450 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
31460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31470 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31480 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31490 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
314a0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
314b0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
314c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
314d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
314e0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
314f0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
31500 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
31510 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
31520 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
31530 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
31540 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
31550 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
31560 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31570 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31580 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31590 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
315a0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
315b0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
315c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
315d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
315e0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
315f0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
31600 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
31610 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31620 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
31630 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
31640 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
31650 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
31660 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31670 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
31680 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
31690 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
316a0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
316b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
316c0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
316d0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
316e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
316f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
31700 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
31710 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31720 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
31730 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
31740 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
31750 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
31760 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
31770 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
31780 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
31790 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
317a0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
317b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
317c0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
317d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
317e0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
317f0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
31800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
31810 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
31820 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
31830 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
31840 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
31850 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
31860 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
31870 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
31880 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
31890 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
318a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
318b0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
318c0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
318d0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
318e0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
318f0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
31900 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
31910 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
31920 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
31930 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31940 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
31950 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
31960 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
31970 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
31980 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
31990 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
319a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
319b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
319c0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
319d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
319e0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
319f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
31a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31a10 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
31a20 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
31a30 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
31a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31a50 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
31a60 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
31a70 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
31a80 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
31a90 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
31aa0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
31ab0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
31ac0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
31ad0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
31ae0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
31af0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
31b00 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
31b10 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
31b20 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
31b30 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
31b40 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
31b50 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
31b60 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
31b70 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
31b80 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
31b90 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
31ba0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31bb0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
31bc0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
31bd0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31be0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
31bf0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
31c00 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
31c10 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
31c20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31c30 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
31c40 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
31c50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31c60 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31c70 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
31c80 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
31c90 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
31ca0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31cb0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
31cc0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
31cd0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
31ce0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
31cf0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
31d00 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
31d10 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
31d20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
31d30 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
31d40 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
31d50 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
31d60 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
31d70 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
31d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31d90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
31da0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
31db0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
31dc0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
31dd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
31de0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
31df0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
31e00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
31e10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
31e20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
31e30 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
31e40 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
31e50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
31e60 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
31e70 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
31e80 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
31e90 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
31ea0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
31eb0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
31ec0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
31ed0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
31ee0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
31ef0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
31f00 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
31f10 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
31f20 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
31f30 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
31f40 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
31f50 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
31f60 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
31f70 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
31f80 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
31f90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
31fa0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
31fb0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
31fc0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
31fd0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
31fe0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
31ff0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
32000 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
32010 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
32020 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
32030 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
32040 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
32050 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
32060 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
32070 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
32080 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
32090 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
320a0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
320b0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
320c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
320d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
320e0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
320f0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
32100 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
32110 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
32120 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
32130 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
32140 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
32150 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
32160 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
32170 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
32180 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
32190 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
321a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
321b0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
321c0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
321d0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
321e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
321f0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
32200 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
32210 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
32220 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
32230 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
32240 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
32250 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
32260 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
32270 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32280 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
32290 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
322a0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
322b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
322c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
322d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
322e0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
322f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32300 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
32310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
32320 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
32330 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
32340 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32350 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
32360 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
32370 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
32380 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
32390 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
323a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
323b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
323c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
323d0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
323e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
323f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32400 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
32410 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
32420 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
32430 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32440 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
32450 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
32460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32470 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
32480 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
32490 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
324a0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
324b0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
324c0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
324d0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
324e0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
324f0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
32500 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
32510 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
32520 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
32530 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
32540 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
32550 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
32560 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
32570 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
32580 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
32590 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
325a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
325b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
325c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
325d0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
325e0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
325f0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
32600 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
32610 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
32620 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
32630 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
32640 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
32650 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
32660 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
32670 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
32680 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
32690 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
326a0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
326b0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
326c0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
326d0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
326e0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
326f0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
32700 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
32710 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
32720 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
32730 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
32740 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
32750 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
32760 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
32770 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
32780 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
32790 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
327a0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
327b0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
327c0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
327d0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
327e0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
327f0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
32800 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
32810 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
32820 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
32830 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
32840 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
32850 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
32860 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
32870 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
32880 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
32890 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
328a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
328b0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
328c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
328d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
328e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
328f0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
32900 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
32910 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
32920 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
32930 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32940 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32950 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
32960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
32970 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
32980 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
32990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
329a0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
329b0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
329c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
329d0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
329e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
329f0 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
32a00 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
32a10 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
32a20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
32a30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
32a40 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
32a50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
32a60 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
32a70 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
32a80 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
32a90 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
32aa0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
32ab0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
32ac0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32ad0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
32ae0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
32af0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
32b00 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
32b10 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
32b20 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
32b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
32b40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32b50 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
32b60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32b70 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
32b80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32b90 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
32ba0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
32bb0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
32bc0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
32bd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
32be0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
32bf0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
32c00 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
32c10 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
32c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
32c30 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
32c40 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
32c50 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
32c60 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
32c70 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
32c80 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
32c90 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
32ca0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
32cb0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
32cc0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
32cd0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
32ce0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
32cf0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
32d00 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
32d10 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
32d20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
32d30 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
32d40 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
32d50 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
32d60 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
32d70 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
32d80 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
32d90 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
32da0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
32db0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
32dc0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
32dd0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
32de0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
32df0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
32e00 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
32e10 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
32e20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
32e30 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
32e40 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
32e50 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
32e60 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
32e70 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
32e80 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
32e90 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
32ea0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
32eb0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
32ec0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
32ed0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
32ee0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
32ef0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
32f00 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
32f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
32f20 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
32f30 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
32f40 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
32f50 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
32f60 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
32f70 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
32f80 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
32f90 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
32fa0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
32fb0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
32fc0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
32fd0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
32fe0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
32ff0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
33000 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
33010 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
33020 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
33030 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
33040 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
33050 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
33060 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
33070 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
33080 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
33090 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
330a0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
330b0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
330c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
330d0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
330e0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
330f0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
33100 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
33110 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
33120 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
33130 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
33140 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
33150 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
33160 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
33170 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
33180 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
33190 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
331a0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
331b0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
331c0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
331d0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
331e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
331f0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
33200 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
33210 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
33220 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
33230 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
33240 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
33250 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
33260 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
33270 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
33280 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
33290 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
332a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
332b0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
332c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
332d0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
332e0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
332f0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
33300 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
33310 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
33320 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
33330 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
33340 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
33350 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
33360 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
33370 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
33380 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
33390 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
333a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
333b0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
333c0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
333d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
333e0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
333f0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
33400 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
33410 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
33420 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
33430 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
33440 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
33450 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
33460 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33470 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
33480 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
33490 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
334a0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
334b0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
334c0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
334d0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
334e0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
334f0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
33500 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
33510 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
33520 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
33530 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
33540 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
33550 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
33560 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
33570 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
33580 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
33590 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
335a0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
335b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
335c0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
335d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
335e0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
335f0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
33600 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
33610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
33620 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
33630 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
33640 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
33650 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
33660 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
33670 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
33680 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
33690 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
336a0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
336b0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
336c0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
336d0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
336e0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
336f0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
33700 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
33710 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
33720 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
33730 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
33740 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
33750 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
33760 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
33770 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
33780 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
33790 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
337a0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
337b0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
337c0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
337d0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
337e0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
337f0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
33800 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
33810 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
33820 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
33830 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
33840 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
33850 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
33860 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
33870 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
33880 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
33890 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
338a0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
338b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
338c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
338d0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
338e0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
338f0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
33900 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
33910 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
33920 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
33930 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
33940 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
33950 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
33960 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
33970 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
33980 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
33990 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
339a0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
339b0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
339c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
339d0 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
339e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
339f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
33a00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
33a10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33a20 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
33a30 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
33a40 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
33a50 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
33a60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33a70 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
33a80 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
33a90 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33aa0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
33ab0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
33ac0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
33ad0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
33ae0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
33af0 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
33b00 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
33b10 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
33b20 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
33b30 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
33b40 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
33b50 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
33b60 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33b70 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
33b80 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33b90 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
33ba0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
33bb0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
33bc0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
33bd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
33be0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
33bf0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
33c00 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
33c10 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
33c20 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
33c30 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
33c40 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
33c50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
33c60 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
33c70 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
33c80 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
33c90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
33ca0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
33cb0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
33cc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33cd0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
33ce0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
33cf0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
33d00 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
33d10 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33d20 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
33d30 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
33d40 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
33d50 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
33d60 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
33d70 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
33d80 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33d90 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
33da0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
33db0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
33dc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
33dd0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
33de0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
33df0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
33e00 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
33e10 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
33e20 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
33e30 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
33e40 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
33e50 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
33e60 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
33e70 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
33e80 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
33e90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
33ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
33eb0 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
33ec0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
33ed0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
33ee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33ef0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
33f00 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
33f10 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
33f20 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
33f30 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
33f40 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
33f50 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
33f60 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
33f70 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
33f80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
33f90 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
33fa0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
33fb0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
33fc0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
33fd0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
33fe0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
33ff0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
34000 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
34010 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
34020 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
34030 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
34040 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
34050 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
34060 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
34070 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
34080 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
34090 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
340a0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
340b0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
340c0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
340d0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
340e0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
340f0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
34100 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
34110 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
34120 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
34130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
34140 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
34150 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
34160 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
34170 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
34180 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
34190 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
341a0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
341b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
341c0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
341d0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
341e0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
341f0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
34200 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
34210 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
34220 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
34230 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
34240 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
34250 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d  mt.**.** <b>Summ
34260 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f  ary:</b>.** <blo
34270 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62  ckquote><table b
34280 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64  order=0 cellpadd
34290 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e  ing=0 cellspacin
342a0 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  g=0>.** <tr><td>
342b0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
342c0 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72  n_blob</b><td>&r
342d0 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73  arr;<td>BLOB res
342e0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
342f0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34300 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26  _double</b><td>&
34310 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65  rarr;<td>REAL re
34320 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
34330 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34340 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  n_int</b><td>&ra
34350 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e  rr;<td>32-bit IN
34360 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
34370 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34380 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c  e3_column_int64<
34390 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
343a0 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >64-bit INTEGER 
343b0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
343c0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
343d0 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e  umn_text</b><td>
343e0 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20  &rarr;<td>UTF-8 
343f0 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
34400 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c  3_column_text16<
34420 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
34430 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73  >UTF-16 TEXT res
34440 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
34450 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34460 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72  _value</b><td>&r
34470 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75  arr;<td>The resu
34480 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71  lt as an .** [sq
34490 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72  lite3_value|unpr
344a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
344b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
344c0 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b  * <tr><td>&nbsp;
344d0 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
344e0 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  bsp;.** <tr><td>
344f0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34500 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26  n_bytes</b><td>&
34510 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  rarr;<td>Size of
34520 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20   a BLOB.** or a 
34530 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
34540 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  t in bytes.** <t
34550 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34560 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26  _column_bytes16&
34570 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a  nbsp;&nbsp;</b>.
34580 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62  ** <td>&rarr;&nb
34590 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a  sp;&nbsp;<td>Siz
345a0 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54  e of UTF-16.** T
345b0 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  EXT in bytes.** 
345c0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
345d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f  e3_column_type</
345e0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
345f0 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74  Default.** datat
34600 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
34610 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62  t.** </table></b
34620 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
34630 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e   <b>Details:</b>
34640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
34650 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
34660 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
34670 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
34680 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
34690 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
346a0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
346b0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
346c0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
346d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
346e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
346f0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
34700 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
34710 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
34720 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
34730 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
34740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
34750 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
34760 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
34770 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
34780 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
34790 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
347a0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
347b0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
347c0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
347d0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
347e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
347f0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
34800 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
34810 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
34820 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
34830 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34840 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
34850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
34860 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
34870 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
34880 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
34890 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
348a0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
348b0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
348c0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
348d0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
348e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
348f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34900 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
34910 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
34920 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
34930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
34940 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
34950 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
34960 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
34970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
34980 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34990 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
349a0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
349b0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
349c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
349d0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
349e0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
349f0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
34a00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34a10 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
34a20 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
34a30 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
34a40 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
34a50 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
34a60 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
34a70 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
34a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34a90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
34aa0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34ab0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
34ac0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
34ad0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
34ae0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
34af0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
34b00 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
34b10 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34b20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34b30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73  *.** The first s
34b40 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f  ix interfaces (_
34b50 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f  blob, _double, _
34b60 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65  int, _int64, _te
34b70 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29  xt, and _text16)
34b80 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20  .** each return 
34b90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72  the value of a r
34ba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20  esult column in 
34bb0 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20  a specific data 
34bc0 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74  format.  If.** t
34bd0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
34be0 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c   is not initiall
34bf0 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74  y in the request
34c00 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65  ed format (for e
34c10 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68  xample,.** if th
34c20 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20  e query returns 
34c30 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74  an integer but t
34c40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
34c50 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61  n_text() interfa
34c60 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f  ce.** is used to
34c70 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c   extract the val
34c80 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f  ue) then an auto
34c90 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
34ca0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
34cb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34cc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34cd0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
34ce0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
34cf0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
34d00 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
34d10 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
34d20 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
34d30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
34d40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
34d50 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
34d60 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
34d70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
34d80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
34d90 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
34da0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
34db0 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  L]..** The retur
34dc0 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74  n value of sqlit
34dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34de0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
34df0 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20  decide which.** 
34e00 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78  of the first six
34e10 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
34e20 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74  d be used to ext
34e30 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ract the column 
34e40 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61  value..** The va
34e50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
34e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34e70 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
34e80 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a  aningful if no.*
34e90 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  * automatic type
34ea0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
34eb0 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74  e occurred for t
34ec0 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73  he value in ques
34ed0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72  tion.  .** After
34ee0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
34ef0 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  on, the result o
34f00 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  f calling sqlite
34f10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
34f20 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c  ** is undefined,
34f30 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73   though harmless
34f40 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
34f50 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
34f60 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
34f70 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
34f80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34f90 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
34fa0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
34fb0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
34fc0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
34fd0 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c  r a TEXT string,
34fe0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
34ff0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35000 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
35010 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35020 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62  interfaces can b
35030 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d  e used to determ
35040 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20  ine the size.** 
35050 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  of that BLOB or 
35060 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
35070 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35080 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
35090 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
350a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
350b0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
350c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
350d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
350e0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
350f0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
35100 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
35110 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
35120 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35130 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
35140 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
35150 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
35160 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
35170 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
35180 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
35190 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
351a0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
351b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
351c0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
351d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
351e0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
351f0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
35200 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
35210 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
35220 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
35230 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
35240 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
35250 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
35260 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
35270 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
35280 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35290 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
352a0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
352b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
352c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
352d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
352e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
352f0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
35300 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
35310 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35320 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
35330 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
35340 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35350 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
35360 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
35370 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
35380 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35390 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
353a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
353b0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
353c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
353d0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
353e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
353f0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
35400 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
35410 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35420 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
35430 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35440 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
35450 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
35460 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
35470 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35480 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
35490 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
354a0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
354b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
354c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
354d0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
354e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
354f0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
35500 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
35510 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
35520 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
35530 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
35540 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
35550 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
35560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35570 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
35580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35590 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
355a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
355b0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
355c0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
355d0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
355e0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
355f0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
35600 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
35610 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
35620 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
35630 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
35640 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
35650 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
35660 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
35670 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
35680 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
35690 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
356a0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
356b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
356c0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
356d0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
356e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
356f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
35700 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
35710 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35720 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
35730 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
35740 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
35750 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
35760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
35770 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
35780 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
35790 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
357a0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
357b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
357c0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
357d0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
357e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
357f0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
35800 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
35810 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
35820 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
35830 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
35840 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
35850 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
35860 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
35870 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
35880 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
35890 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
358a0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
358b0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
358c0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48  threadsafe..** H
358d0 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  ence, the sqlite
358e0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
358f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
35900 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75   normally only u
35910 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65  seful within the
35920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35930 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74  of .** [applicat
35940 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
35950 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76  functions] or [v
35960 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20  irtual tables], 
35970 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f  not within.** to
35980 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74  p-level applicat
35990 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ion code..**.** 
359a0 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  The these routin
359b0 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  es may attempt t
359c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61  o convert the da
359d0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
359e0 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78  sult..** ^For ex
359f0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
35a00 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
35a10 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
35a20 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
35a30 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
35a40 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
35a50 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
35a60 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
35a70 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
35a80 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
35a90 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
35aa0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
35ab0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
35ac0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
35ad0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
35ae0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
35af0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
35b00 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
35b10 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
35b20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
35b30 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
35b40 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
35b50 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
35b60 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35b70 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
35b80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
35b90 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
35ba0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
35bb0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
35bc0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
35bd0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
35be0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
35bf0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
35c00 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35c10 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35c20 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
35c30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
35c40 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
35c50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35c60 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
35c70 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
35c80 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
35c90 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
35ca0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
35cb0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
35cc0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
35cd0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35ce0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35cf0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
35d00 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
35d10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35d20 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35d30 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
35d40 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
35d50 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
35d60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
35d70 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
35d80 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
35d90 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35da0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35db0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
35dc0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
35dd0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
35de0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
35df0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
35e00 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35e10 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35e20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35e30 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
35e40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
35e50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
35e60 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
35e70 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35e80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35e90 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35ea0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35eb0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
35ec0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
35ed0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
35ee0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35ef0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
35f00 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
35f10 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
35f20 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
35f30 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
35f40 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
35f50 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
35f60 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
35f70 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
35f80 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
35f90 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
35fa0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
35fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35fc0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
35fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35fe0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
35ff0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
36000 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
36010 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
36020 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
36030 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
36040 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
36050 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
36060 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
36070 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
36080 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
36090 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
360a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
360b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
360c0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
360d0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
360e0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
360f0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
36100 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
36110 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
36120 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
36130 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
36140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36150 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
36160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36170 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
36180 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
36190 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
361a0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
361b0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
361c0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
361d0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
361e0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
361f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36200 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
36210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36220 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
36230 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
36240 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
36250 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
36260 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
36270 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
36280 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
36290 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
362a0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
362b0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
362c0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
362d0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
362e0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
362f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36300 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
36310 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
36320 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
36330 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
36340 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
36350 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
36360 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
36370 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
36380 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
36390 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
363a0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
363b0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
363c0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
363d0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
363e0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
363f0 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
36400 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
36410 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
36420 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
36430 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
36440 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
36450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36460 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
36470 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36480 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
36490 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
364a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
364b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
364c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
364d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
364e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
364f0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
36500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36510 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
36520 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
36530 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
36540 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
36550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36560 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
36570 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
36580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36590 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
365a0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
365b0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
365c0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
365d0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
365e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
365f0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
36600 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36610 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
36620 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
36630 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
36640 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
36650 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
36660 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
36670 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
36680 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
36690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
366a0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
366b0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
366c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
366d0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
366e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
366f0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
36700 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
36710 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
36720 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
36730 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36740 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
36750 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
36760 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
36770 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
36780 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
36790 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
367a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
367b0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
367c0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
367d0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
367e0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
367f0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e  matically.  Do n
36800 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ot pass the poin
36810 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
36820 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
36830 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
36840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36850 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
36860 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
36870 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
36880 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
36890 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
368a0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
368b0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
368c0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
368d0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
368e0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
368f0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
36900 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
36910 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
36920 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
36930 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
36940 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
36950 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
36960 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
36970 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
36980 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
36990 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
369a0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
369b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
369c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
369d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
369e0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
369f0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
36a00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36a10 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36a20 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
36a30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36a40 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
36a50 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
36a60 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
36a70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36a80 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
36a90 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
36aa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
36ab0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36ac0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
36ad0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
36ae0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
36af0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36b00 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
36b10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36b20 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
36b30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36b50 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
36b60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36b70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36b80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
36b90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36ba0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
36bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36bd0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
36be0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
36bf0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
36c00 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
36c10 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
36c20 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
36c30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
36c40 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
36c50 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
36c60 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
36c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
36c80 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36c90 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
36ca0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
36cb0 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
36cc0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
36cd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
36ce0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
36cf0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
36d00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
36d10 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
36d20 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
36d30 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
36d40 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
36d50 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
36d60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
36d70 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
36d80 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
36d90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
36da0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
36db0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
36dc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
36dd0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
36de0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
36df0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
36e00 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
36e10 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
36e20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
36e30 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
36e40 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
36e50 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
36e60 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
36e70 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36e80 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
36e90 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
36ea0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
36eb0 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
36ec0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
36ed0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
36ee0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
36ef0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
36f00 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
36f10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
36f20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36f30 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
36f40 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
36f50 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
36f60 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
36f70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36f80 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
36f90 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
36fa0 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
36fb0 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
36fc0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
36fd0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
36fe0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
36ff0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
37000 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
37010 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
37020 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
37030 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
37040 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
37050 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
37060 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
37070 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
37080 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
37090 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
370a0 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
370b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
370c0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
370d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
370e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
370f0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
37100 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
37110 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
37120 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
37130 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
37140 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
37150 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
37160 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
37170 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
37180 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
37190 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
371a0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
371b0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
371c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
371d0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
371e0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
371f0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
37200 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
37210 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
37220 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
37230 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
37240 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
37250 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
37260 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
37270 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
37280 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
37290 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
372a0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
372b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
372c0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
372d0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
372e0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
372f0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
37300 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
37310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
37320 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
37330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37340 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
37350 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
37360 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
37370 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
37380 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
37390 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
373a0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
373b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
373c0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
373d0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
373e0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
373f0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
37400 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
37410 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
37420 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
37430 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
37440 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
37450 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
37460 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
37470 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
37480 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
37490 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
374a0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
374b0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
374c0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
374d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
374e0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
374f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
37500 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
37510 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
37520 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
37530 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
37540 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
37550 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
37560 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
37570 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
37580 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
37590 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
375a0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
375b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
375c0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
375d0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
375e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
375f0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
37600 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
37610 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
37620 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
37630 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
37640 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
37650 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
37660 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
37670 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
37680 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
37690 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
376a0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
376b0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
376c0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
376d0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
376e0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
376f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
37700 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
37710 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
37720 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
37730 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
37740 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
37750 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
37760 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
37770 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
37780 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
37790 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
377a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
377b0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
377c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
377d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
377e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
377f0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
37800 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
37810 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
37820 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
37830 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
37840 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
37850 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
37860 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
37870 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37880 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
37890 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
378a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
378b0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
378c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
378d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
378e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
378f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37900 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
37910 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
37920 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
37930 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
37940 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
37950 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
37960 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
37970 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
37980 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
37990 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
379a0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
379b0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
379c0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
379d0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
379e0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
379f0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
37a00 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
37a10 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
37a20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
37a30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
37a40 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
37a50 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
37a60 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
37a70 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
37a80 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
37a90 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
37aa0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37ab0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
37ac0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
37ad0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
37ae0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
37af0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
37b00 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
37b10 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
37b20 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
37b30 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
37b40 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
37b50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
37b60 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
37b70 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
37b80 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
37b90 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
37ba0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
37bb0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
37bc0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
37bd0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37be0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
37bf0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
37c00 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
37c10 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
37c20 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
37c30 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
37c40 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
37c50 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
37c60 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
37c70 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
37c80 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
37c90 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
37ca0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
37cb0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
37cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
37cd0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
37ce0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
37cf0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
37d00 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
37d10 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
37d20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37d30 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
37d40 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
37d50 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
37d60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37d70 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
37d80 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
37d90 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
37da0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
37db0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
37dc0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
37dd0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
37de0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
37df0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
37e00 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
37e10 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
37e20 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
37e30 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
37e40 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
37e50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37e60 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
37e70 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
37e80 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
37e90 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
37ea0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
37eb0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
37ec0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
37ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
37ee0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
37ef0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
37f00 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
37f10 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
37f20 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
37f30 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
37f40 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
37f50 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
37f60 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
37f70 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
37f80 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
37f90 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
37fa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
37fb0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
37fc0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
37fd0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
37fe0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
37ff0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
38000 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
38010 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
38020 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
38030 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
38040 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
38050 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
38060 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
38070 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
38080 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
38090 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
380a0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
380b0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
380c0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
380d0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
380e0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
380f0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
38100 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
38110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
38120 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
38130 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
38140 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
38150 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
38160 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
38170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
38180 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
38190 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
381a0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
381b0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
381c0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
381d0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
381e0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
381f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
38200 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
38210 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
38220 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
38230 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
38240 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
38250 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
38260 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
38270 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
38280 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
38290 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
382a0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
382b0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
382c0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
382d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
382e0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
382f0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
38300 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
38310 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
38320 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
38330 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
38340 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
38350 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
38360 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
38370 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
38380 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
38390 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
383a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
383b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
383c0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
383d0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
383e0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
383f0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
38400 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
38410 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
38420 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
38430 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
38440 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
38450 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
38460 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
38470 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
38480 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
38490 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
384a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
384b0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
384c0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
384d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
384e0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
384f0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
38500 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
38510 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
38520 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
38530 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
38540 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
38550 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
38560 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
38570 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38580 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
38590 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
385a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
385b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
385c0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
385d0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
385e0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
385f0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
38600 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
38610 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
38620 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
38630 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
38640 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
38650 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
38660 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
38670 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
38680 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
38690 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
386a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
386b0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
386c0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
386d0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
386e0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
386f0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
38700 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
38710 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
38720 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
38730 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
38740 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
38750 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
38760 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
38770 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
38780 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63