/ Hex Artifact Content
Login

Artifact 19de593baa0667854730e7b8bc2e3039c20ee80a4d537e9b5ec2038947fe3daf:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
59f0: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5a10: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5a70: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5a90: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ab0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5ac0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5ad0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5ae0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5af0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5b00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5b10: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5b40: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5b50: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5b60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b70: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5b80: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5b90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5ba0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5bc0: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5bd0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5be0: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5bf0: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5c00: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c10: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5c20: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5c30: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c40: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5c50: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5c60: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5c70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5c90: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5cb0: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5cd0: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5cf0: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5d10: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5d30: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d50: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d70: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d90: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5da0: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5db0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5de0: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5df0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5e00: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5e10: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5e20: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5e30: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5e60: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5e70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5e80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5e90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ea0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5eb0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ec0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ee0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5ef0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5f00: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5f10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5f20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5f30: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5f40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5f50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5f60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f70: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5f80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5fb0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5fc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5fd0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ff0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
6000: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
6010: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
6020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6030: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
6040: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
6050: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6060: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6070: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6080: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6090: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
60a0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
60b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
60c0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
60d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
60e0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
60f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6100: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
6110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
6120: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
6130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6140: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
6150: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6160: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6180: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
61a0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
61c0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
61d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
61e0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
6200: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
6210: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
6220: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
6230: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
6240: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
6250: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6260: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6270: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6280: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6290: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
62a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
62b0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
62c0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
62d0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
62e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
62f0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
6300: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6310: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
6320: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6330: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
6340: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6360: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6370: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6380: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6390: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6410: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
6420: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
6430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6440: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
6450: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6460: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6480: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6490: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
64a0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
64b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64c0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
64d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
64e0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
64f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6510: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6520: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6530: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6540: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6590: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
65b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65c0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
65d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65e0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
65f0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
6600: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
6610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6620: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6630: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6640: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6650: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6660: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6670: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6680: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6690: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
66b0: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
66c0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
66d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
66f0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
6700: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6710: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6720: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6730: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6740: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6750: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6770: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6780: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6790: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
67d0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6820: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6870: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6880: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6890: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
68a0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
68b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
68c0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
68d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
68e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
68f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6900: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6910: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6930: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6940: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6950: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6960: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6970: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6980: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6990: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
69a0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
69b0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
69c0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
69d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
69e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
69f0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6a00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a10: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6a20: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6a30: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6a40: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6a50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6a70: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6a80: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6a90: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6aa0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6ab0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6ac0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6ad0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6ae0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6af0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6b00: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b10: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6b20: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6b30: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6b40: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6b50: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6b60: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6b70: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6b80: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6b90: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6ba0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6bb0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6bc0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6bd0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6be0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6bf0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6c00: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6c10: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6c20: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6c30: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6c40: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6c50: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6c60: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6c70: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6c80: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6c90: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6ca0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6cb0: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6cc0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6cd0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6ce0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6cf0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6d00: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6d10: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6d20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6d30: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6d50: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6d70: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6d80: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6d90: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6da0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6db0: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6dc0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6dd0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6de0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6df0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6e00: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6e10: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6e20: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6e30: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6e40: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6e50: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6e60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6e70: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6e80: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6e90: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6ea0: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6eb0: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6ec0: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6ed0: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6ee0: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6ef0: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6f00: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6f10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6f20: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6f30: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6f40: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6f50: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6f70: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6f80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f90: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fb0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6fc0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6fe0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ff0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7000: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
7010: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7020: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7030: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
7040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7050: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7060: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7070: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7080: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
70a0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
70b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70c0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
70d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
70e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7100: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7110: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
7140: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
7150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7160: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7170: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7180: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
71a0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
71b0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
71c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71d0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
71e0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
71f0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7200: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7210: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
7220: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7240: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
7250: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7260: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7270: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7280: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7290: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
72a0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
72b0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
72c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
72d0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
72e0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
72f0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7300: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
7310: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
7320: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7330: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
7340: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
7350: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7360: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7370: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7380: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
73a0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
73b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
73c0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
73d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
73e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
73f0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7400: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7410: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
7420: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
7430: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
7440: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
7450: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7460: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7470: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7480: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7490: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
74a0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
74b0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
74c0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
74d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
74e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
74f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7500: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
7510: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
7520: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
7530: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
7540: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
7550: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7560: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7570: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7580: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7590: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
75a0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
75b0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
75c0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
75d0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
75e0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
75f0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7600: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7610: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
7620: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
7630: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
7640: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7650: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7660: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7670: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7680: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7690: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
76a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
76b0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
76c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76d0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
76e0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76f0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7700: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7710: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
7720: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
7730: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7740: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7750: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7760: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7770: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7780: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7790: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
77a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
77b0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
77c0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
77d0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
77e0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
77f0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7800: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7810: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
7820: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
7830: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7840: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7850: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7860: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7870: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7880: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7890: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
78a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
78b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
78c0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
78d0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
78e0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
78f0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7900: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7910: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
7920: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
7930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7940: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7950: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7960: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7970: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7980: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7990: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
79a0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
79b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
79c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
79d0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
79e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
79f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7a00: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7a10: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7a20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7a30: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7a40: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7a50: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7a60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7a70: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7a80: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7a90: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7aa0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7ab0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7ac0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7ad0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7ae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7af0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7b00: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7b10: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7b20: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7b30: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7b40: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7b50: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7b60: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7b70: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7b80: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7b90: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7ba0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7bb0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7bc0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7bd0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7be0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7bf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7c00: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7c10: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7c20: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7c30: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7c40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7c50: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7c60: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c80: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7c90: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7ca0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7cd0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7ce0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7cf0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7d00: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7d10: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7d20: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7d40: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7d50: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7d60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7d70: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7d80: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7d90: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7da0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7db0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7dc0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7dd0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7de0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7e00: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7e10: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7e20: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7e30: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7e40: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7e50: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7e60: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7e70: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7e80: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7e90: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7ea0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7eb0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7ec0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7ed0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7ee0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7ef0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7f00: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7f10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7f20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7f30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7f40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7f50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7f60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7f70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7f80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7f90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7fa0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7fb0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7fc0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7fd0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7fe0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7ff0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
8000: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
8010: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
8020: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
8030: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
8040: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
8050: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8060: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8070: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8080: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8090: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
80a0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
80b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
80c0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
80d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
80e0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
80f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8100: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
8110: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8120: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
8130: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
8140: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
8150: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8160: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8170: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8180: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8190: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
81a0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
81b0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
81c0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
81d0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
81e0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
81f0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8200: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
8210: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
8220: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
8230: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
8240: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
8250: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8260: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8270: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8280: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8290: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
82a0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
82b0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
82c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
82d0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
82e0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
82f0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8300: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8310: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
8320: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
8330: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
8340: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
8350: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8360: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8370: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8380: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8390: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
83a0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
83b0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
83c0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
83d0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
83e0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
83f0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8400: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
8410: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
8420: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
8430: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
8440: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
8450: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8460: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8470: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8480: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8490: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
84a0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
84b0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
84c0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
84d0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
84e0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
84f0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8500: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
8510: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
8520: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
8530: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
8540: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
8550: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8560: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8570: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8580: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8590: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
85a0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
85b0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
85c0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
85d0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
85e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
85f0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8600: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
8610: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
8620: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
8630: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
8640: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
8650: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8660: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8670: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8680: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8690: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
86a0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
86b0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
86c0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
86d0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
86e0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
86f0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8700: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8710: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8720: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8730: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
8740: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
8750: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8760: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8770: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8780: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8790: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
87a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
87b0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
87c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
87d0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8800: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8810: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8820: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8830: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8840: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8850: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8860: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8870: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8880: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8890: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
88a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88b0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
88c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
88d0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
88e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
88f0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8900: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8910: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
8920: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
8940: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8950: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8960: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8970: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8980: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8990: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
89a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
89b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
89c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
89d0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
89e0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
89f0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8a10: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8a20: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8a30: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8a40: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8a50: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8a60: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8a70: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8a80: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8a90: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8aa0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8ac0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8ad0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8ae0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8af0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8b00: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b10: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8b20: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8b30: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8b40: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8b50: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8b70: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8b80: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8b90: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8ba0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8bb0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8bc0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8bd0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8be0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8bf0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8c00: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8c10: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8c20: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8c30: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8c40: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8c50: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8c60: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8c70: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c80: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8c90: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8ca0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8cb0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8cc0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8cd0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8ce0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8cf0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8d00: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8d10: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8d20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8d30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8d40: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8d50: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8d60: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8d80: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8d90: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8da0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8db0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8dc0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8dd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8de0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8df0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8e00: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8e10: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8e20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8e40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e60: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8e70: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8e80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8e90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8ea0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8eb0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8ec0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8ed0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8ee0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8ef0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8f00: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8f10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8f20: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8f30: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8f40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f50: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8f60: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8f70: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8f80: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f90: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8fa0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8fb0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8fc0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8fd0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8fe0: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8ff0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
9000: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
9010: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
9020: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
9030: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
9040: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9050: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9060: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9070: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9080: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9090: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
90a0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
90b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
90c0: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
90d0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
90e0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
90f0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9100: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
9110: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
9120: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
9130: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
9140: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
9150: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9160: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9170: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9180: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9190: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
91a0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
91b0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
91c0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
91d0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
91e0: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
91f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9200: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
9210: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
9220: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
9230: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
9240: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
9250: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9260: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9270: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9280: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9290: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
92a0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
92b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
92c0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
92d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
92e0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
92f0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9300: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9310: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9320: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9330: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
9340: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9350: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9360: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9370: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9390: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
93a0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
93b0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
93c0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
93d0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
93e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
93f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9400: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
9410: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
9420: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
9430: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
9440: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
9450: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9460: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9470: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9480: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9490: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
94a0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
94b0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
94c0: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
94d0: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
94e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
94f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9500: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
9520: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
9530: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
9540: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
9550: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9560: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9570: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9580: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9590: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
95a0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
95b0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
95c0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
95d0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
95e0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
95f0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9600: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9610: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
9620: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
9630: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
9640: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
9650: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9660: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9670: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9680: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
96a0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
96b0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
96c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
96d0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
96e0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
96f0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9700: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9710: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
9720: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
9730: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
9740: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9750: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9760: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9770: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9780: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9790: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
97a0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
97b0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
97c0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
97d0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
97e0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
97f0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9800: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9810: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
9820: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
9830: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9840: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9850: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9860: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9870: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9880: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9890: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
98a0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
98b0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
98c0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
98d0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
98e0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
98f0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9900: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9910: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9920: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9930: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9940: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9950: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9960: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9970: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9980: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9990: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
99a0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
99b0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
99c0: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
99d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
99e0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
99f0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9a00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9a10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
9a20: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
9a30: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
9a40: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
9a50: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9a60: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9a70: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9a80: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9a90: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9ab0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9ac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ad0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9ae0: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9af0: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9b20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9b30: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9b40: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9b50: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9b60: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9b70: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9b80: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9b90: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9ba0: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9bb0: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9bc0: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9bd0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9be0: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9bf0: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9c00: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9c10: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9c20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9c30: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9c40: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9c50: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9c60: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9c70: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9c80: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9c90: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9ca0: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9cb0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9cc0: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9cd0: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9ce0: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9cf0: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9d00: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9d10: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9d20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9d30: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9d40: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9d50: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9d60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9d70: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9d80: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9d90: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9da0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9db0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9dc0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9dd0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9de0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9df0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9e00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9e10: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9e20: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9e30: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9e40: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9e50: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9e60: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9e70: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9e80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e90: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9ea0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9eb0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9ec0: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9ed0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9ee0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9ef0: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9f00: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9f10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9f20: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9f30: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9f40: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9f50: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9f60: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9f70: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9f80: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9f90: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9fa0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9fb0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9fc0: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9fd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9fe0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9ff0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
a000: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
a010: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
a020: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
a030: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
a040: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
a070: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
a080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a090: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
a0a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a0b0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
a0c0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
a0d0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
a0e0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
a0f0: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
a100: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
a110: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
a120: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a130: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
a140: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
a150: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
a160: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
a170: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
a180: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
a190: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
a1a0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
a1b0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
a1c0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
a1d0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
a1e0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
a1f0: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
a200: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
a210: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
a220: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
a230: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
a240: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a250: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
a260: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
a270: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
a280: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
a290: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
a2a0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
a2b0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
a2c0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
a2d0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
a2e0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
a2f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a300: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
a310: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a320: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
a330: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
a340: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
a350: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
a360: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
a370: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
a380: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
a390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
a3a0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
a3b0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
a3c0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
a3d0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
a3e0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
a3f0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
a400: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
a410: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
a420: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
a430: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
a440: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
a450: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a460: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a470: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a480: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a490: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a4a0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a4c0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a4e0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a4f0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a500: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a510: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a520: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a530: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a540: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a550: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a560: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a570: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a580: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a590: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a5a0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a5b0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a5c0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a5d0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a5e0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a5f0: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a600: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a610: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a620: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a630: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a640: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a650: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a660: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a670: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a680: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a690: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a6a0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a6b0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a6c0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a6d0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a6e0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a6f0: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a700: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a710: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a720: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a730: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a740: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a750: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a760: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a770: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a780: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a790: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a7a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a7b0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a7c0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a7d0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a7e0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a7f0: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a800: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a810: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a820: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a830: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a840: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a850: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a860: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a880: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a890: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a8a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a8b0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a8c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a8d0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a8e0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a8f0: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a900: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a910: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a920: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a930: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a940: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a950: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a960: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a980: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a990: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a9a0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a9b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a9c0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a9d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a9e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a9f0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
aa00: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
aa10: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa20: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
aa30: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa40: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
aa50: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
aa60: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
aa70: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
aa80: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
aa90: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
aaa0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
aab0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
aac0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aae0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
aaf0: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
ab00: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
ab10: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
ab20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
ab30: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
ab40: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
ab50: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
ab60: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
ab70: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
ab80: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
ab90: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
aba0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
abb0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
abc0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
abd0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
abe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
abf0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
ac00: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ac10: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
ac20: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
ac30: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
ac40: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
ac50: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
ac60: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
ac70: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
ac80: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
ac90: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
aca0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
acb0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
acc0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
acd0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ace0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
acf0: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
ad00: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
ad10: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
ad20: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
ad30: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
ad40: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
ad50: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
ad60: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
ad70: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
ad80: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
ad90: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
ada0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
adb0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
adc0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
add0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
ade0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
adf0: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
ae00: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
ae10: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
ae20: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
ae30: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
ae40: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
ae50: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
ae60: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
ae70: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
ae80: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
ae90: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
aea0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
aeb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aec0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
aed0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aee0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aef0: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
af00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
af10: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
af20: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
af30: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
af40: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
af50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
af60: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
af70: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af80: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
af90: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
afa0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
afb0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
afc0: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
afd0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
afe0: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
aff0: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
b000: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
b010: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
b020: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
b030: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
b040: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
b050: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b060: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b070: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
b080: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
b090: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
b0a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
b0b0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
b0c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
b0d0: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
b0e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b0f0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
b100: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
b110: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
b120: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
b130: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
b140: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
b150: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
b160: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b170: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
b180: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
b190: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
b1a0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
b1b0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
b1c0: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
b1d0: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
b1e0: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
b1f0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
b200: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
b210: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
b220: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
b230: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
b240: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
b250: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
b260: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
b270: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b280: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
b290: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
b2a0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
b2b0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
b2c0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
b2d0: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
b2e0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b2f0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
b300: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
b310: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
b320: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
b330: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
b340: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
b350: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
b360: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
b370: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
b380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b390: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b3a0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b3b0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
b3c0: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
b3d0: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
b3e0: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
b3f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b400: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b410: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b420: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
b430: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
b440: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
b450: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b460: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b470: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b480: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b490: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b4a0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b4b0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b4c0: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b4d0: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b4e0: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b4f0: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b500: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b510: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b520: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b530: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b540: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b550: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b560: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b570: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b580: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b590: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b5a0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b5b0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b5c0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b5d0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b5e0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b5f0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b600: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b620: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b630: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b640: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b650: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b660: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b670: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b680: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b690: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b6a0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b6b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b6c0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b6d0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b6f0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b700: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b710: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b720: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b730: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b740: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b750: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b760: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b770: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b780: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b790: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b7a0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b7b0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b7c0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b7d0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b7e0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b7f0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b800: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b810: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b820: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b830: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b840: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b850: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b860: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b870: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b880: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b890: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b8a0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b8b0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b8c0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b8d0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b8e0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b8f0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b900: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b910: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b920: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b930: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b940: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b950: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b960: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b980: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b990: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b9a0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b9b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b9c0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b9d0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b9e0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b9f0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
ba00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
ba10: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
ba20: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
ba30: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
ba40: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
ba50: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
ba60: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
ba70: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ba80: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ba90: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
baa0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
bab0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
bac0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
bad0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
bae0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
baf0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
bb00: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
bb10: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
bb20: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
bb30: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
bb40: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
bb50: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
bb60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bb70: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
bb80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bb90: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
bba0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bbb0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
bbc0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
bbd0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
bbe0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
bbf0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
bc00: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
bc10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bc20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bc30: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
bc40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
bc50: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
bc60: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
bc70: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
bc80: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
bc90: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
bca0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
bcb0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
bcc0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
bcd0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
bce0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
bcf0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
bd00: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
bd10: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
bd20: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
bd30: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
bd40: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
bd50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
bd60: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
bd70: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
bd80: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
bd90: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
bda0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
bdb0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
bdc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bdd0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
bde0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bdf0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
be00: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
be10: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
be20: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
be30: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
be40: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
be50: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
be60: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
be70: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be80: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
be90: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
bea0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
beb0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
bec0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
bed0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
bee0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
bef0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
bf00: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
bf10: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bf20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
bf30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bf40: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
bf50: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bf60: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bf70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf80: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf90: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bfa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bfb0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bfc0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bfd0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bfe0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bff0: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
c000: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
c010: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
c020: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
c030: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
c040: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
c050: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
c060: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
c070: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
c080: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
c090: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c0a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c0b0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c0c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
c0e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
c0f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
c100: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
c110: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c120: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
c130: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
c140: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
c150: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c160: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c170: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c180: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c190: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
c1a0: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
c1b0: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
c1c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c1d0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c1e0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c200: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
c210: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
c220: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
c230: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
c240: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
c250: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
c260: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
c270: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
c280: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
c290: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
c2a0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
c2b0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
c2c0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
c2d0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
c2e0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
c2f0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
c300: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c310: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c320: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c330: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c340: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c350: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
c360: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
c370: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
c380: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
c390: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
c3a0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
c3b0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
c3c0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
c3d0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
c3e0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
c3f0: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
c400: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
c410: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
c420: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
c430: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
c440: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
c450: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c460: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c470: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c480: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c490: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c4a0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c4b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c4c0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c4d0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c4e0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c4f0: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c500: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c520: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c530: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c550: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c560: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c570: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c580: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c590: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c5a0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c5b0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c5c0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c5d0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c5e0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c5f0: 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  pcode.  .**.** <
c600: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c610: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c620: 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65  RITE]].** If the
c630: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c640: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c650: 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e  E] opcode return
c660: 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65  s SQLITE_OK, the
c670: 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65  n.** the file de
c680: 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63  scriptor is plac
c690: 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69  ed in "batch wri
c6a0: 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a  te mode", which.
c6b0: 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62  ** means all sub
c6c0: 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70  sequent write op
c6d0: 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  erations will be
c6e0: 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f   deferred and do
c6f0: 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79  ne.** atomically
c700: 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51   at the next [SQ
c710: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c720: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  T_ATOMIC_WRITE].
c730: 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61    Systems.** tha
c740: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  t do not support
c750: 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72   batch atomic wr
c760: 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e  ites will return
c770: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c780: 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20  ..** ^Following 
c790: 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c  a successful SQL
c7a0: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c7b0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64  ATOMIC_WRITE and
c7c0: 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65   prior to.** the
c7d0: 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45   closing [SQLITE
c7e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c7f0: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a  OMIC_WRITE] or.*
c800: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c810: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c820: 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77  WRITE], SQLite w
c830: 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56  ill make.** no V
c840: 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  FS interface cal
c850: 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ls on the same [
c860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69  sqlite3_file] fi
c870: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a  le descriptor.**
c880: 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c   except for call
c890: 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20  s to the xWrite 
c8a0: 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78  method and the x
c8b0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
c8c0: 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49  od.** with [SQLI
c8d0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c8e0: 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  NT]..**.** <li>[
c8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c900: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c910: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c920: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c930: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c940: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
c950: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
c960: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
c970: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
c980: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
c990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c9a0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c9b0: 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  to be performed 
c9c0: 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54  atomically..** T
c9d0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c9e0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
c9f0: 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK] if and only
ca00: 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77   if the writes w
ca10: 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f  ere.** all perfo
ca20: 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  rmed successfull
ca30: 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20  y and have been 
ca40: 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72  committed to per
ca50: 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e  sistent storage.
ca60: 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
ca70: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
ca80: 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  t it is successf
ca90: 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f  ul, this file co
caa0: 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74  ntrol takes.** t
cab0: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cac0: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cad0: 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68  write mode so th
cae0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
caf0: 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  t.** write opera
cb00: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cb10: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cb20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cb30: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cb40: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cb50: 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20  RITE without.** 
cb60: 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
cb70: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49  ul call to [SQLI
cb80: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cb90: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a  TOMIC_WRITE]..**
cba0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cbb0: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cbc0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cbd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cbe0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cbf0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
cc00: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
cc10: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
cc20: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
cc30: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
cc40: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
cc50: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cc60: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
cc70: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  be rolled back..
cc80: 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f  ** ^This file co
cc90: 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20  ntrol takes the 
cca0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
ccb0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ccc0: 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68  te mode.** so th
ccd0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
cce0: 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t write operatio
ccf0: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
cd00: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
cd10: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cd20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
cd30: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
cd40: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cd50: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cd60: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cd70: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd80: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cd90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cda0: 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f  FCNTL_LOCK_TIMEO
cdb0: 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  UT]].** The [SQL
cdc0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
cdd0: 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63  IMEOUT] opcode c
cde0: 61 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74  auses attempts t
cdf0: 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69  o obtain.** a fi
ce00: 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68  le lock using th
ce10: 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c  e xLock or xShmL
ce20: 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ock methods of t
ce30: 68 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a  he VFS to wait.*
ce40: 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69  * for up to M mi
ce50: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
ce60: 65 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65  e failing, where
ce70: 20 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65   M is the single
ce80: 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e   .** unsigned in
ce90: 74 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e  teger parameter.
cea0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
ceb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cec0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
ced0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
cee0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cef0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
cf00: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
cf10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cf20: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
cf30: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
cf40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
cf50: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
cf60: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
cf70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
cf80: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
cf90: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
cfa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
cfb0: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
cfc0: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
cfd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
cfe0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
cff0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
d000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
d010: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
d020: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
d030: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d040: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
d050: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
d060: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
d070: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
d080: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
d090: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
d0a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
d0b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d0c0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
d0d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
d0e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d0f0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
d100: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
d110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d120: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
d130: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
d140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d150: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
d160: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
d170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d180: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
d190: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
d1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d1b0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
d1c0: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
d1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d1e0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
d1f0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
d200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d210: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
d220: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
d230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d240: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
d250: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
d260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
d270: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
d280: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
d290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d2a0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
d2b0: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
d2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
d2d0: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
d2e0: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
d2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
d300: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
d310: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
d320: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
d330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d340: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
d350: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
d360: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
d370: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
d380: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
d390: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
d3a0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d3b0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
d3c0: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
d3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d3e0: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
d3f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
d400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d410: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
d420: 43 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23  C_WRITE     31.#
d430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d440: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
d450: 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64  C_WRITE    32.#d
d460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d470: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
d480: 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65  IC_WRITE  33.#de
d490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d4a0: 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20  L_LOCK_TIMEOUT  
d4b0: 20 20 20 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20           34../* 
d4c0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
d4d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d4e0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
d4f0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
d500: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
d510: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
d520: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
d530: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
d540: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
d550: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
d560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
d570: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
d580: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d590: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
d5a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
d5b0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
d5c0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
d5d0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
d5e0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
d5f0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
d600: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
d610: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
d620: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
d630: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
d640: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
d650: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
d660: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
d670: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
d680: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
d690: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
d6a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d6b0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
d6c0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
d6d0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d6e0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
d6f0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
d700: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
d710: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
d720: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
d730: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
d740: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
d750: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
d760: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
d770: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d780: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
d790: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
d7a0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
d7b0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
d7c0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
d7d0: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
d7e0: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
d7f0: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
d800: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
d810: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
d820: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
d830: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
d840: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d850: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
d860: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
d870: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
d880: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
d890: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
d8a0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
d8b0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d8c0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
d8d0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
d8e0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
d8f0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
d900: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
d910: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
d920: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
d930: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
d940: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
d950: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
d960: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
d970: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
d980: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
d990: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
d9a0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
d9b0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
d9c0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
d9d0: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
d9e0: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
d9f0: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
da00: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
da10: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
da20: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
da30: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
da40: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
da50: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
da60: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
da70: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
da80: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
da90: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
daa0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
dab0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
dac0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
dad0: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
dae0: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
daf0: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
db00: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
db10: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
db20: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
db30: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
db40: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
db50: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
db60: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
db70: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
db80: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
db90: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
dba0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
dbb0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
dbc0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
dbd0: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
dbe0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
dbf0: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
dc00: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
dc10: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
dc20: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
dc30: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
dc40: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
dc50: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
dc60: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
dc70: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
dc80: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
dc90: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
dca0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
dcb0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
dcc0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
dcd0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
dce0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
dcf0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
dd00: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
dd10: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
dd20: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
dd30: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
dd40: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
dd50: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
dd60: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
dd70: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
dd80: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
dd90: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
dda0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
ddb0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
ddc0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
ddd0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
dde0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
ddf0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
de00: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
de10: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
de20: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
de30: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
de40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
de50: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
de60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
de70: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
de80: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
de90: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
dea0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
deb0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
dec0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
ded0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
dee0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
def0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
df00: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
df10: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
df20: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
df30: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
df40: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
df50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
df60: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
df70: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
df80: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
df90: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
dfa0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
dfb0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
dfc0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
dfd0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
dfe0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
dff0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e000: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e010: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e020: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e030: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e040: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e050: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e060: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e070: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e080: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e090: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e0a0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e0b0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e0c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e0d0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e0e0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e0f0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e100: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e110: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e120: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e130: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e140: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e150: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e160: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e170: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e180: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e190: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e1a0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e1b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e1c0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
e1d0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
e1e0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
e1f0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
e200: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
e210: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
e220: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
e230: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
e240: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
e250: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
e260: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
e270: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
e280: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
e290: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
e2a0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e2b0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
e2c0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
e2d0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
e2e0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
e2f0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
e300: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
e310: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
e320: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
e330: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
e340: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
e350: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
e360: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
e370: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
e380: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e390: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
e3a0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
e3b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
e3c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
e3d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
e3e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
e3f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
e400: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
e410: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e420: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
e430: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
e440: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
e450: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
e460: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
e470: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
e480: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e490: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
e4a0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
e4b0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
e4c0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
e4d0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
e4e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e4f0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
e500: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
e510: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
e520: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
e530: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e540: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e550: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e560: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
e570: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
e580: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
e590: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e5a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e5b0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e5d0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
e5e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e5f0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
e600: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e610: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
e620: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e630: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
e640: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
e650: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
e660: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
e670: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e680: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
e690: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e6a0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
e6b0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
e6c0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
e6d0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
e6e0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
e6f0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
e700: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
e710: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
e720: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
e730: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e740: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
e750: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
e760: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
e770: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
e780: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
e790: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
e7a0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
e7b0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
e7c0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
e7d0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
e7e0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
e7f0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
e800: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
e810: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
e820: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e830: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
e840: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
e850: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
e860: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
e870: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
e880: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
e890: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
e8a0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
e8b0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
e8c0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
e8d0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
e8e0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e8f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e900: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
e910: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e920: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e930: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e940: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
e950: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e960: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
e970: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e980: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e990: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
e9a0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e9b0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
e9c0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
e9d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e9e0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e9f0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
ea00: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
ea10: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
ea20: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
ea30: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
ea40: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
ea50: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
ea60: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
ea70: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
ea80: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
ea90: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
eaa0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
eab0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
eac0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
ead0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
eae0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
eaf0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
eb00: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
eb10: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
eb20: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
eb30: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
eb40: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
eb50: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
eb60: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
eb70: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
eb80: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
eb90: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
eba0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
ebb0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
ebc0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
ebd0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
ebe0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
ebf0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
ec00: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
ec10: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
ec20: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
ec30: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
ec40: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
ec50: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
ec60: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
ec70: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
ec80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
ec90: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
eca0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
ecb0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
ecc0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
ecd0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
ece0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
ecf0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
ed00: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
ed10: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
ed20: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
ed30: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
ed40: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
ed50: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
ed60: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
ed70: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
ed80: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ed90: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
eda0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
edb0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
edc0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
edd0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
ede0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
edf0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
ee00: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
ee10: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
ee20: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
ee30: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
ee40: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
ee50: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
ee60: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
ee70: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
ee80: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
ee90: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
eea0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
eeb0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
eec0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
eed0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
eee0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
eef0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ef00: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
ef10: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
ef20: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
ef30: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
ef40: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ef50: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
ef60: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
ef70: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
ef80: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
ef90: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
efa0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
efb0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
efc0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
efd0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
efe0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
eff0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
f000: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
f010: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
f020: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
f030: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
f040: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
f050: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
f060: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
f070: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
f080: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
f090: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f0a0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
f0b0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
f0c0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
f0d0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
f0e0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
f0f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
f100: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
f110: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
f120: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
f130: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
f140: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
f150: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
f160: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
f170: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
f180: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
f190: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
f1a0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
f1b0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
f1c0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
f1d0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
f1e0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
f1f0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
f200: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
f210: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
f220: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
f230: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
f240: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
f250: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
f260: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
f270: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
f280: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
f290: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
f2a0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
f2b0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
f2c0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
f2d0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
f2e0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
f2f0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
f300: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
f310: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
f320: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
f330: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
f340: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
f350: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
f360: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
f370: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
f380: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
f390: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
f3a0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
f3b0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
f3c0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f3d0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
f3e0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
f3f0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
f400: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
f410: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
f420: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
f430: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
f440: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
f450: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f460: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
f470: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f480: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
f490: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
f4a0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
f4b0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
f4c0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
f4d0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
f4e0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
f4f0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f500: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
f510: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
f520: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
f530: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
f540: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
f550: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
f560: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
f570: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
f580: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
f590: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
f5a0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
f5b0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
f5c0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
f5d0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
f5e0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
f5f0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
f600: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
f610: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
f620: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
f630: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
f640: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
f650: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
f660: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
f670: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
f680: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
f690: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
f6a0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
f6b0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
f6c0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
f6d0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
f6e0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
f6f0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
f700: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
f710: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
f720: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
f730: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
f740: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
f750: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
f760: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
f770: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
f780: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
f790: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
f7a0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
f7b0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
f7c0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
f7d0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
f7e0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
f7f0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
f800: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
f810: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
f820: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
f830: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
f840: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
f850: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
f860: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
f870: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
f880: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
f890: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f8a0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
f8b0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
f8c0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f8d0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
f8e0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
f8f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
f900: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f910: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
f920: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
f930: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
f940: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
f950: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
f960: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
f970: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
f980: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
f990: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
f9a0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
f9b0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
f9c0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
f9d0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
f9e0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
f9f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fa00: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
fa10: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
fa20: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
fa30: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
fa40: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
fa50: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
fa60: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
fa70: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
fa80: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
fa90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
faa0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
fab0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
fac0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
fad0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
fae0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
faf0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fb00: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fb10: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
fb20: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
fb30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fb40: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
fb50: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
fb60: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
fb70: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
fb80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fb90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
fba0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
fbb0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
fbc0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
fbd0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fbe0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
fbf0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
fc00: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
fc10: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
fc20: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
fc30: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
fc40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
fc50: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
fc60: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
fc70: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
fc80: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
fc90: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
fca0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
fcb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fcc0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
fcd0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
fce0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
fcf0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
fd00: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
fd10: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
fd20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
fd30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
fd40: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
fd50: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
fd60: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
fd70: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
fd80: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
fd90: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
fda0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
fdb0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
fdc0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
fdd0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
fde0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
fdf0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
fe00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
fe10: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
fe20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
fe30: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
fe40: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
fe50: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
fe60: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
fe70: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fe80: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
fe90: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
fea0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
feb0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
fec0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fed0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fee0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
fef0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ff00: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ff10: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
ff20: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ff30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ff40: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ff50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ff60: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ff70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ff80: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ff90: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ffa0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ffb0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
ffc0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
ffd0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ffe0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
fff0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10000 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
10010 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10020 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10030 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10040 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10050 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10070 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
10080 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
10090 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
100a0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
100b0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
100c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
100d0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
100e0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
100f0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10100 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10110 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10120 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10130 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10140 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10150 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10160 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10170 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
10180 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
10190 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
101a0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
101b0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
101c0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
101d0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
101e0 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
101f0 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10200 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10210 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10220 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10230 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10240 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10250 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10260 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10270 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10280 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10290 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
102a0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
102b0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
102c0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
102d0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
102e0 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
102f0 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10300 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10310 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
10320 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
10330 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10340 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10350 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10360 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
10370 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
10380 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10390 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
103a0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
103b0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
103c0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
103d0 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
103e0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
103f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10400 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
10410 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
10420 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10430 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
10440 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
10450 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10470 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10480 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10490 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
104a0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
104b0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
104c0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
104d0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
104e0 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
104f0 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10500 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10510 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
10520 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
10530 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10540 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
10550 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
10560 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
10570 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10580 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10590 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
105a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
105b0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
105c0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
105d0 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
105e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
105f0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10600 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10610 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
10620 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10630 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10640 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10650 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
10660 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
10670 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10680 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10690 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
106a0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
106b0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
106c0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
106d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
106e0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
106f0 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10700 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10710 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
10720 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
10730 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
10740 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
10750 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
10760 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
10770 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10780 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10790 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
107a0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
107b0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
107c0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
107d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
107e0 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
107f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10800 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
10810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10820 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
10830 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
10840 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
10850 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
10860 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
10870 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
10880 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
10890 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
108a0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
108b0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
108c0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
108d0 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
108e0 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
108f0 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
10900 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
10910 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
10920 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
10930 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
10940 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
10950 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
10960 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
10970 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10980 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10990 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
109a0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
109b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
109c0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
109d0 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
109e0 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
109f0 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
10a00 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
10a10 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
10a20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
10a30 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
10a40 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
10a50 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
10a60 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
10a70 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
10a80 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
10a90 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
10aa0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
10ab0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
10ac0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
10ad0 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
10ae0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
10af0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
10b00 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
10b10 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
10b20 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
10b30 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
10b40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10b50 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
10b60 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
10b70 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
10b80 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
10b90 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10ba0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10bb0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
10bc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
10bd0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10be0 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
10bf0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10c00 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
10c20 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
10c30 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
10c40 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
10c50 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
10c60 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
10c70 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10c80 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
10c90 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
10ca0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
10cb0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
10cc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
10cd0 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
10ce0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10cf0 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
10d00 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
10d10 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10d20 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
10d30 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
10d40 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
10d50 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
10d60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
10d70 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10d80 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
10d90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10da0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
10db0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
10dc0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
10dd0 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
10de0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
10df0 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
10e00 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
10e10 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
10e20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
10e30 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
10e40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10e50 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
10e60 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
10e70 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
10e80 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
10e90 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
10ea0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
10eb0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
10ec0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
10ed0 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
10ee0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
10ef0 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
10f00 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10f10 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
10f20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
10f30 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
10f40 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10f60 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10f90 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10fa0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10fb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10fc0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10fd0 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10fe0 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10ff0 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11000 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11010 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11020 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11030 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11040 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11050 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11060 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
11070 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11080 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
11090 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
110a0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
110b0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
110c0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
110d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
110e0 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
110f0 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11100 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11110 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11120 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11130 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11140 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11150 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11160 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11170 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
11180 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
11190 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
111a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
111b0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
111c0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
111d0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
111e0 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
111f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11200 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11210 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11220 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11230 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11240 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11250 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11260 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11270 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11280 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11290 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
112a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
112b0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
112c0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
112d0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
112e0 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
112f0 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11300 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11310 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
11320 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
11330 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
11340 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
11350 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
11360 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11370 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11380 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
11390 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
113a0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
113b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
113c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
113d0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
113e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
113f0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11400 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
11410 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
11420 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
11430 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
11440 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
11450 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
11460 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11470 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11480 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11490 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
114a0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
114b0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
114c0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
114d0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
114e0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
114f0 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11500 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11510 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
11520 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
11530 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
11540 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
11550 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
11560 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
11570 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11580 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11590 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
115a0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
115b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
115c0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
115d0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
115e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
115f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11600 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
11620 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
11630 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
11640 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
11650 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
11660 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
11670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11680 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11690 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
116a0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
116b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
116c0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
116d0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
116e0 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
116f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11700 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11710 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
11720 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
11730 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
11740 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
11750 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
11760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
11770 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11780 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11790 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
117a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
117b0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
117c0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
117d0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
117e0 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
117f0 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
11800 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
11810 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
11820 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
11830 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
11840 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
11850 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
11860 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
11870 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
11880 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
11890 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
118a0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
118b0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
118c0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
118d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
118e0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
118f0 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
11900 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
11910 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11920 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
11930 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
11940 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
11950 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
11960 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
11970 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
11980 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11990 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
119a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
119b0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
119c0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
119d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
119e0 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
119f0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11a10 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11a20 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11a30 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
11a40 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
11a50 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
11a60 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
11a70 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11a80 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11aa0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11ab0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11ac0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11ad0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11ae0 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11af0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11b00 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
11b10 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
11b20 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
11b30 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
11b40 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
11b50 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
11b60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
11b70 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11b80 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
11b90 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
11ba0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
11bb0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11bc0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11bd0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11be0 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11bf0 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11c00 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
11c10 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
11c20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11c30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
11c40 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
11c50 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
11c60 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
11c70 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
11c80 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11c90 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
11ca0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
11cb0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
11cc0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
11cd0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
11ce0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
11cf0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
11d00 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
11d10 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11d20 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
11d30 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
11d40 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
11d50 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
11d60 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
11d70 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
11d80 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
11d90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
11da0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
11db0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
11dc0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
11dd0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11de0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
11df0 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
11e00 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
11e10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
11e20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
11e30 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
11e40 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
11e50 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
11e60 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
11e70 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
11e80 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
11e90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ea0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
11eb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
11ec0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
11ed0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11ee0 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
11ef0 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11f00 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11f10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11f20 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11f30 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11f40 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11f50 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11f60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11f70 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11f80 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
11f90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11fa0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
11fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11fc0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
11fd0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11fe0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11ff0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12000 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12010 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12020 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12030 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12040 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12050 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12060 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
12070 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
12080 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
12090 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
120a0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
120b0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
120c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
120d0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
120e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
120f0 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12100 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12110 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12120 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12130 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12140 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12150 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12160 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
12170 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
12180 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
12190 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
121a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
121b0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
121c0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
121d0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
121e0 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
121f0 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12200 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12210 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12220 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12230 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12240 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12250 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12260 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
12270 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
12280 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12290 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
122a0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
122b0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
122c0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
122d0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
122e0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
122f0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
12300 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
12310 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
12320 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12330 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12340 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
12350 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
12360 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
12370 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12380 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12390 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
123a0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
123b0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
123c0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
123d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123e0 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
123f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12400 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12410 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
12420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12430 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
12440 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
12450 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12460 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
12470 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12480 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12490 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
124a0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
124b0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
124c0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
124d0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
124e0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
124f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12500 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12510 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
12520 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
12530 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
12540 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
12550 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
12560 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
12570 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12580 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12590 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
125a0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
125b0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
125c0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
125d0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
125e0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
125f0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12600 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12610 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
12620 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
12630 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12640 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
12650 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
12660 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
12670 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12680 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12690 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
126a0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
126b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
126c0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
126d0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
126e0 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
126f0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12700 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12710 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
12720 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
12730 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
12740 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
12750 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
12760 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
12770 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12780 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12790 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
127a0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
127b0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
127c0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
127d0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
127e0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
127f0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12800 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12810 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
12820 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
12830 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
12840 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
12850 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
12860 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
12870 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12880 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12890 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
128a0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
128b0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
128c0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
128d0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
128e0 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
128f0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12900 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12910 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
12920 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
12930 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
12940 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
12950 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
12960 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
12970 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12980 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12990 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
129a0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
129b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
129c0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
129d0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
129e0 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
129f0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12a00 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12a10 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
12a20 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
12a30 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
12a40 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
12a50 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
12a60 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
12a70 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12a80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12a90 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12aa0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12ab0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12ac0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12ad0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12ae0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12af0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12b00 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12b10 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
12b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12b30 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
12b40 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
12b50 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
12b60 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
12b70 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
12b80 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
12b90 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
12ba0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
12bb0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
12bc0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
12bd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
12be0 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
12bf0 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
12c00 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
12c10 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
12c20 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
12c30 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
12c40 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
12c50 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
12c60 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
12c70 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
12c80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12c90 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
12ca0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
12cb0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
12cc0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
12cd0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
12ce0 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
12cf0 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
12d00 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
12d10 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
12d20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12d30 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
12d40 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
12d50 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
12d60 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
12d70 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
12d80 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
12d90 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12da0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
12db0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
12dc0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12dd0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
12de0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12df0 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
12e00 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
12e10 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
12e20 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
12e30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
12e40 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
12e50 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
12e60 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12e70 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
12e80 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
12e90 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
12ea0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
12eb0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
12ec0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
12ed0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
12ee0 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
12ef0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12f00 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
12f10 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
12f20 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
12f30 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
12f40 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
12f50 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12f60 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12f70 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
12f80 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
12f90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12fa0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
12fb0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
12fc0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
12fd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12fe0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12ff0 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
13000 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
13010 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
13020 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
13030 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
13040 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
13050 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13060 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
13070 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
13080 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
13090 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
130a0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
130b0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
130c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
130d0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
130e0 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
130f0 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
13100 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
13110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
13120 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13130 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
13140 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
13150 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
13160 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
13170 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
13180 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
13190 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
131a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
131b0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
131c0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
131d0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
131e0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
131f0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
13200 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
13210 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13220 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
13230 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
13240 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13250 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13260 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13270 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13280 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
13290 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
132a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
132b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
132c0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
132d0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
132e0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
132f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
13300 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
13310 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13320 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
13330 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
13340 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13350 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13360 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13370 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13380 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13390 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
133a0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
133b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
133c0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
133d0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
133e0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
133f0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
13400 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
13410 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
13420 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
13430 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
13440 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
13450 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13460 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13470 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13480 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13490 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
134a0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
134b0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
134c0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
134d0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
134e0 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
134f0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13500 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13510 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
13520 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
13530 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
13540 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
13550 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
13560 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
13570 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13580 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13590 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
135a0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
135b0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
135c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
135d0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
135e0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
135f0 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13600 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13610 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
13620 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
13630 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
13640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13650 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
13660 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13670 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13680 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13690 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
136a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
136b0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
136c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
136d0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
136e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
136f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13700 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13710 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13720 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13730 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13740 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13750 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
13760 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
13770 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13780 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13790 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
137a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
137b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
137c0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
137d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
137e0 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
137f0 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
13800 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
13810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13820 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
13830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
13840 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
13850 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
13860 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
13870 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
13880 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
13890 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
138a0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
138b0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
138c0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
138d0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
138e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
138f0 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
13900 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
13910 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13920 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13930 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13940 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13950 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13960 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13970 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13980 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
13990 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
139a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
139b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
139c0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
139d0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
139e0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
139f0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13a00 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13a10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13a20 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
13a30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13a40 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
13a50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13a60 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
13a70 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13a80 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13a90 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13aa0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13ab0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13ac0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
13ad0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
13ae0 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
13af0 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
13b00 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
13b10 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
13b20 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
13b30 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
13b40 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
13b50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13b60 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
13b70 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
13b80 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
13b90 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13ba0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13bb0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13bc0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
13bd0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
13be0 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
13bf0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
13c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13c10 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
13c20 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
13c30 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
13c40 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
13c50 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
13c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13c70 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
13c80 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
13c90 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
13ca0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
13cb0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13cc0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13cd0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13ce0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13cf0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13d00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13d10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13d20 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13d30 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13d40 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
13d50 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
13d60 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
13d70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13d80 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13d90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13da0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13db0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13dc0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
13dd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13de0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13e00 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13e10 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
13e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13e30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13e40 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
13e50 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13e60 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
13e70 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13e80 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13ea0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13eb0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13ec0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13ed0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13ee0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13ef0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13f00 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13f10 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
13f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13f30 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
13f40 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13f50 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
13f60 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
13f70 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
13f80 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13f90 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13fa0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
13fb0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
13fc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
13fd0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13fe0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13ff0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
14000 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14010 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
14020 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14030 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14040 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
14050 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14060 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
14070 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14080 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14090 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
140a0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
140b0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
140c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
140d0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
140e0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
140f0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14100 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
14110 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
14120 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14130 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14140 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14150 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
14160 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
14170 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
14180 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
14190 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
141a0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
141b0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
141c0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
141d0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
141e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
141f0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
14200 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14210 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
14220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14240 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
14250 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14260 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
14270 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
14280 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14290 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
142a0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
142b0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
142c0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
142d0 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
142e0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
142f0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
14300 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
14310 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
14320 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
14330 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14340 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
14350 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
14360 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
14370 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
14380 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
14390 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
143a0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
143b0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
143c0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
143d0 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
143e0 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
143f0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
14400 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14410 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14420 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
14430 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14440 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
14450 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14460 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14470 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14480 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14490 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
144a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
144b0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
144c0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
144d0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
144e0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
144f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14500 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14520 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
14530 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
14540 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
14550 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
14560 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
14570 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14580 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14590 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
145a0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
145b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
145c0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
145d0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
145e0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
145f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14600 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14610 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
14620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14630 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14640 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
14650 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
14660 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14670 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14680 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14690 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
146a0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
146b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
146c0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
146d0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
146e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
146f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14700 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14710 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
14720 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
14730 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14740 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
14750 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
14760 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14780 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14790 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
147a0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
147b0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
147c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
147d0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
147e0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
147f0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14800 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
14810 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
14820 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
14830 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
14840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
14850 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
14860 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
14870 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
14880 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14890 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
148a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
148b0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
148c0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
148d0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
148e0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
148f0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14900 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14910 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
14920 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
14930 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
14940 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
14950 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
14960 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
14970 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
14980 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
14990 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
149a0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
149b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
149c0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
149d0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
149e0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
149f0 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
14a00 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
14a10 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
14a20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
14a30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
14a40 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
14a50 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
14a60 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
14a70 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
14a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14a90 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
14aa0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
14ab0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14ac0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14ad0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
14ae0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
14af0 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
14b00 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
14b10 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
14b20 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
14b30 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
14b40 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
14b50 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
14b60 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
14b70 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
14b80 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
14b90 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14ba0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
14bb0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
14bc0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
14bd0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
14be0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
14bf0 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
14c00 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
14c10 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
14c20 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
14c30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
14c40 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
14c50 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
14c60 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
14c70 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
14c80 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
14c90 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
14ca0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
14cb0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
14cc0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
14cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14ce0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
14cf0 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
14d00 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
14d10 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
14d20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
14d30 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
14d40 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
14d50 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
14d60 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
14d70 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
14d80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
14d90 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14da0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14db0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14dc0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14dd0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
14de0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
14df0 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
14e00 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14e10 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
14e20 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
14e30 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
14e40 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
14e50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14e60 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
14e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14e80 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
14e90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ea0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
14eb0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
14ec0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
14ed0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
14ee0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
14ef0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
14f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14f10 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
14f20 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
14f30 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
14f40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14f50 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14f60 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14f70 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14f80 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14f90 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14fa0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14fb0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14fc0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14fd0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14fe0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14ff0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
15000 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
15010 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
15020 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
15030 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15040 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
15050 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
15060 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
15070 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
15080 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
15090 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
150a0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
150b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
150c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
150d0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
150e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
150f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15100 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15110 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
15120 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15130 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
15140 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
15150 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
15160 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
15170 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
15180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15190 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
151a0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
151b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
151c0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
151d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
151e0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
151f0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15200 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15220 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15230 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15240 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
15250 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
15260 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
15270 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15280 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15290 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
152a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
152b0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
152c0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
152d0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
152e0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
152f0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15300 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15310 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
15320 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
15330 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15340 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
15350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15360 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
15370 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15380 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15390 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
153a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
153b0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
153c0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
153d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
153e0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
153f0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15400 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15410 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
15420 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
15430 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15440 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
15450 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
15460 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
15470 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15480 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15490 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
154a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
154b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
154c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
154d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
154f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15560 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15570 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15580 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15590 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
155a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
155b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
155c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
155d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
155e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
155f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15610 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15620 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15630 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
15640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15650 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15660 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15670 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15680 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15690 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
156a0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
156b0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
156c0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
156d0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
156e0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
156f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15700 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15710 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
15720 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
15730 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
15740 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
15750 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
15760 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15770 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15780 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15790 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
157a0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
157b0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
157c0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
157d0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
157e0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
157f0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
15800 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
15810 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15820 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
15830 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
15840 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
15850 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15860 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
15870 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15880 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15890 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
158a0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
158b0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
158c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
158d0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
158e0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
158f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15900 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15910 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15920 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
15940 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
15950 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15960 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
15970 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15980 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
15990 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
159a0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
159b0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
159c0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
159d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
159e0 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
159f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
15a00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15a10 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
15a20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
15a30 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
15a40 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
15a50 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
15a60 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
15a70 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
15a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15a90 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
15aa0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
15ab0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
15ac0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
15ad0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
15ae0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15af0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
15b00 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
15b10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
15b20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
15b30 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
15b40 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
15b50 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
15b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
15b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15b90 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
15ba0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
15bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15bc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15bd0 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
15be0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15bf0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15c00 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
15c10 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15c20 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15c30 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
15c40 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
15c50 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
15c60 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
15c70 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15c80 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
15c90 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15ca0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15cb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15cc0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
15cd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15ce0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
15cf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15d00 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15d10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15d30 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
15d40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15d50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
15d60 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15d70 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15d80 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15d90 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15da0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15db0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15dc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15dd0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15de0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15df0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15e00 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15e10 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
15e20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
15e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15e40 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15e50 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
15e60 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15e70 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15e80 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15e90 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15ea0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15eb0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15ec0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15ed0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15ee0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15ef0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15f00 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15f10 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15f20 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15f30 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15f40 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15f50 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15f60 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15f70 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15f80 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15f90 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15fa0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15fb0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15fc0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15fd0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15fe0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15ff0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
16000 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16010 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
16020 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
16030 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
16040 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16050 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
16060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16070 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
16080 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
16090 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
160a0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
160b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
160c0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
160d0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
160e0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
160f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16100 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16110 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16120 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
16130 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
16140 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
16150 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16160 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
16170 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16180 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
16190 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
161a0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
161b0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
161c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
161d0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
161e0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
161f0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16200 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16210 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
16220 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
16230 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16240 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
16250 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
16260 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
16270 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16280 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16290 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
162a0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
162b0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
162c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
162d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
162e0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
162f0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16300 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16310 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
16320 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16330 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16340 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
16350 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
16360 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16370 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16380 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16390 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
163a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
163b0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
163c0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
163d0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
163e0 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
163f0 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16410 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16420 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
16430 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
16440 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
16450 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
16460 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
16470 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16480 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16490 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
164a0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
164b0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
164c0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
164d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
164e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
164f0 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16500 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16510 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
16520 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
16530 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
16540 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
16550 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
16560 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
16570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16580 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16590 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
165a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
165b0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
165c0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
165d0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
165e0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
165f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16600 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16610 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
16620 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16630 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16640 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
16650 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16660 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
16670 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16680 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16690 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
166a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
166b0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
166c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
166d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
166e0 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
166f0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16700 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16710 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16720 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
16730 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
16740 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
16750 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16760 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
16770 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16780 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16790 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
167a0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
167b0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
167c0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
167d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
167e0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
167f0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
16800 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
16810 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
16820 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
16830 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
16840 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
16850 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
16860 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
16870 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
16880 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
16890 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
168a0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
168b0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
168c0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
168d0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
168e0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
168f0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
16900 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
16910 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
16920 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
16930 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
16940 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
16950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16960 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
16970 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
16980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16990 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
169a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
169b0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
169c0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
169d0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
169e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
169f0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
16a00 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
16a10 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
16a20 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
16a30 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
16a40 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
16a50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16a60 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
16a70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16a80 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
16a90 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
16aa0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16ab0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
16ac0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16ad0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
16ae0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
16af0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
16b00 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
16b10 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
16b20 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
16b30 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
16b40 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
16b50 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
16b60 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
16b70 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
16b80 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
16b90 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
16ba0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
16bb0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
16bc0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
16bd0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
16be0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
16bf0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
16c00 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
16c10 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
16c20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16c30 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
16c40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16c50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
16c60 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16c70 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
16c80 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
16c90 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16ca0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
16cb0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
16cc0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
16cd0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
16ce0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
16cf0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16d00 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
16d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
16d20 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
16d30 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
16d40 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
16d50 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
16d60 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
16d70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16d80 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16d90 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16da0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16db0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16dc0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16dd0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16de0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16df0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16e00 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16e10 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
16e20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16e30 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
16e40 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
16e50 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
16e60 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16e70 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16e80 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16e90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16ea0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16eb0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16ec0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16ed0 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16ee0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16ef0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16f00 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16f10 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16f20 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16f30 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16f40 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16f50 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16f60 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16f70 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16f80 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16f90 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16fa0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16fb0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16fc0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16fd0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16fe0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16ff0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
17000 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
17010 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
17020 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
17030 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
17040 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
17050 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
17060 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
17070 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
17080 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
17090 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
170a0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
170b0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
170c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
170d0 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
170e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
170f0 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17100 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17110 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
17120 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
17130 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
17140 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
17150 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
17160 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
17170 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
17180 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
17190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
171a0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
171b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
171c0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
171d0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
171e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
171f0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17200 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17210 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
17220 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
17230 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
17240 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
17250 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
17260 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
17270 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17280 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17290 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
172a0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
172b0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
172c0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
172d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
172e0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
172f0 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17310 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
17320 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17330 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
17340 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17350 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17360 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
17370 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17380 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
173a0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
173b0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
173c0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
173d0 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
173e0 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
173f0 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17400 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17410 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
17420 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
17430 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
17440 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
17450 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
17460 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
17470 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17480 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17490 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
174a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
174b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
174c0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
174d0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
174e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
174f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17500 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17510 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
17520 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
17530 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
17540 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
17550 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
17560 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
17570 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17580 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17590 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
175a0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
175b0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
175c0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
175d0 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
175e0 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
175f0 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17600 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17610 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
17620 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
17630 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
17640 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
17650 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
17660 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
17670 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17680 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17690 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
176a0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
176b0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
176c0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
176d0 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
176e0 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
176f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17700 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17710 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17720 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17730 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
17740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17750 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
17760 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17770 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17780 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17790 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
177a0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
177b0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
177c0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
177d0 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
177e0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
177f0 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
17800 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
17810 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
17820 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
17830 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
17840 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
17850 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
17860 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
17870 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
17880 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
17890 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
178a0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
178b0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
178c0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
178d0 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
178e0 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
178f0 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
17900 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
17910 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
17920 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
17930 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
17940 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
17950 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
17960 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
17970 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
17980 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
17990 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
179a0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
179b0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
179c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
179d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
179e0 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
179f0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
17a00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
17a10 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  RREF_SIZE.** <dd
17a20 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
17a30 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
17a40 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73  E option accepts
17a50 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17a60 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28  ter.** of type (
17a70 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76  int) - the new v
17a80 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74  alue of the sort
17a90 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a  er-reference siz
17aa0 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20  e threshold..** 
17ab0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51  Usually, when SQ
17ac0 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74  Lite uses an ext
17ad0 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72  ernal sort to or
17ae0 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f  der records acco
17af0 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f  rding.** to an O
17b00 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
17b10 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69  all fields requi
17b20 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  red by the calle
17b30 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e  r are present in
17b40 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72   the.** sorted r
17b50 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c  ecords. However,
17b60 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   if SQLite deter
17b70 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74  mines based on t
17b80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
17b90 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63  .** of a table c
17ba0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76  olumn that its v
17bb0 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  alues are likely
17bc0 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67   to be very larg
17bd0 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68  e - larger.** th
17be0 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65  an the configure
17bf0 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  d sorter-referen
17c00 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
17c10 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72  d - then a refer
17c20 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65  ence.** is store
17c30 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64  d in each sorted
17c40 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20   record and the 
17c50 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20  required column 
17c60 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a  values loaded.**
17c70 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
17c80 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72  se as records ar
17c90 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f  e returned in so
17ca0 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20  rted order. The 
17cb0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
17cc0 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
17cd0 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65   is to never use
17ce0 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
17cf0 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  on. Specifying a
17d00 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61   .** negative va
17d10 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
17d20 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65  ion restores the
17d30 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
17d40 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  ur..** This opti
17d50 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17d60 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17d70 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
17d80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
17d90 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46  NABLE_SORTER_REF
17da0 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65  ERENCES] compile
17db0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
17dc0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17dd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17de0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
17df0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17e10 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
17e20 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17e40 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
17e50 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
17e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17e70 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
17e80 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
17e90 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17eb0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
17ec0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
17ed0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
17ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ef0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
17f00 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f       6  /* No lo
17f10 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
17f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17f30 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
17f40 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
17f50 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
17f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17f70 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
17f80 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
17f90 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
17fa0 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
17fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
17fc0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
17fd0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
17fe0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ff0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
18000 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
18010 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
18020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18030 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
18040 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
18050 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
18060 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
18070 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
18080 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
18090 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
180a0 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
180b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
180c0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
180d0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
180e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
180f0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
18100 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18120 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
18130 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
18140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18150 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
18160 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
18170 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
18180 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18190 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
181a0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
181b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
181c0 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
181d0 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
181e0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
181f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18200 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
18210 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
18220 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
18230 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
18240 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
18250 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
18260 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
18270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18280 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
18290 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
182a0 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
182b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
182c0 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
182d0 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
182e0 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
182f0 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
18300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
18310 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
18320 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
18330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18340 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18350 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
18360 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
18370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18380 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
18390 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
183a0 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
183b0 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
183c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
183d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
183e0 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
183f0 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
18400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
18410 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  L_MALLOC        
18420 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a  27  /* boolean *
18430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18440 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
18450 46 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20  F_SIZE      28  
18460 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
18470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18480 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
18490 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
184a0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
184b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
184c0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
184d0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
184e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
184f0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
18500 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
18510 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
18520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
18530 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
18540 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
18550 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18560 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
18570 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
18580 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
18590 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
185a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
185b0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
185c0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
185d0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
185e0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
185f0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
18600 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18610 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
18620 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
18630 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
18640 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18650 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
18660 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
18670 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
18680 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
18690 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
186a0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
186b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
186c0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
186d0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
186e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
186f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
18700 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18710 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
18720 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18730 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
18740 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
18750 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
18760 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
18770 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
18780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18790 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
187a0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
187b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
187c0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
187d0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
187e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
187f0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
18800 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
18810 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
18820 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
18830 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
18840 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18850 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
18860 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
18870 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
18880 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
18890 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
188a0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
188b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
188c0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
188d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
188e0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
188f0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18900 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
18910 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18920 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
18930 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
18940 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
18950 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18960 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
18970 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
18980 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
18990 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
189a0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
189b0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
189c0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
189d0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
189e0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
189f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
18a00 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
18a10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18a20 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
18a30 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
18a40 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
18a50 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
18a60 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
18a70 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
18a80 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
18a90 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
18aa0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
18ab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18ac0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
18ad0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
18ae0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
18af0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
18b00 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
18b10 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
18b20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
18b30 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
18b40 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
18b50 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
18b60 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
18b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18b80 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
18b90 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
18ba0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
18bb0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
18bc0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
18bd0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
18be0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
18bf0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
18c00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
18c10 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
18c20 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
18c30 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
18c40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18c50 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18c60 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
18c70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18c80 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18c90 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
18ca0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
18cb0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
18cc0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
18cd0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
18ce0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18cf0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
18d00 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
18d10 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
18d20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18d30 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
18d40 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18d50 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
18d60 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
18d70 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
18d80 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
18d90 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
18da0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18db0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18dc0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18dd0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18de0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18df0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
18e00 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
18e10 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
18e20 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18e30 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18e40 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18e50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18e60 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18e70 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18e80 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18e90 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
18ea0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18eb0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18ec0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
18ed0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18ee0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18ef0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18f00 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
18f10 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
18f20 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18f30 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18f40 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18f50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18f60 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18f70 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18f80 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
18f90 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
18fa0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
18fb0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
18fc0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
18fd0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
18fe0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18ff0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19000 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19010 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
19020 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19030 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19040 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
19050 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
19060 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
19070 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19080 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19090 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
190a0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
190b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
190c0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
190d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
190e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
190f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19100 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
19110 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e  3_TOKENIZER</dt>
19120 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19130 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19140 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19150 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d  le the two-argum
19160 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ent.** version o
19170 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65  f the [fts3_toke
19180 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  nizer()] functio
19190 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20  n which is part 
191a0 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d  of the.** [FTS3]
191b0 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
191c0 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69  h engine extensi
191d0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  on..** There sho
191e0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
191f0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19200 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19210 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
19220 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
19230 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f  to disable fts3_
19240 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a  tokenizer() or.*
19250 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19260 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
19270 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76  zer() or negativ
19280 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
19290 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
192a0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
192b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
192c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
192d0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
192e0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
192f0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19300 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33  ate whether fts3
19310 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69  _tokenizer is di
19320 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
19330 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
19340 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19350 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19360 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
19370 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19380 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
19390 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
193a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
193b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
193c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
193d0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
193e0 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ION</dt>.** <dd>
193f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
19400 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19410 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b  or disable the [
19420 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
19430 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74  ension()].** int
19440 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65  erface independe
19450 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61  ntly of the [loa
19460 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
19470 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
19480 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
19490 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
194a0 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65  on()] API enable
194b0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f  s or disables bo
194c0 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  th the.** C-API 
194d0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
194e0 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74  tension()] and t
194f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19500 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
19510 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  )]..** There sho
19520 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
19530 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19540 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72  .** When the fir
19550 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19560 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19570 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68   1, then only th
19580 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e  e C-API is.** en
19590 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51  abled and the SQ
195a0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69  L function remai
195b0 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66  ns disabled.  If
195c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
195d0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
195e0 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
195f0 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
19600 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
19610 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
19620 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
19630 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19640 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
19650 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
19660 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
19670 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
19680 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
19690 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
196a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
196b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
196c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
196d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
196e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
196f0 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
19700 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19710 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
19720 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
19730 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
19740 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19750 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19760 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
19770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19780 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
19790 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
197a0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
197b0 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
197c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
197d0 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
197e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
197f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19800 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
19810 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61   name of the "ma
19820 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  in" database.** 
19830 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f  schema.  ^The so
19840 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  le argument is a
19850 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
19860 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69  nstant UTF8 stri
19870 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  ng.** which will
19880 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20   become the new 
19890 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70  schema name in p
198a0 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20  lace of "main". 
198b0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73   ^SQLite.** does
198c0 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79   not make a copy
198d0 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e   of the new main
198e0 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72   schema name str
198f0 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c  ing, so the appl
19900 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
19910 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
19920 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
19930 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46  into this DBCONF
19940 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63  IG option is unc
19950 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20  hanged.** until 
19960 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61  after the databa
19970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
19980 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  oses..** </dd>.*
19990 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
199a0 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
199b0 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  _ON_CLOSE</dt>.*
199c0 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20  * <dd> Usually, 
199d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
199e0 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63  in wal mode is c
199f0 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65  losed or detache
19a00 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74  d from a .** dat
19a10 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51  abase handle, SQ
19a20 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74  Lite checks if t
19a30 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68  his will mean th
19a40 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77  at there are now
19a50 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69   no .** connecti
19a60 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68  ons at all to th
19a70 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73  e database. If s
19a80 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61  o, it performs a
19a90 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20   checkpoint .** 
19aa0 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65  operation before
19ab0 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e   closing the con
19ac0 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70  nection. This op
19ad0 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64  tion may be used
19ae0 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20   to.** override 
19af0 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20  this behaviour. 
19b00 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19b10 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19b20 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  is operation.** 
19b30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20  is an integer - 
19b40 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61  positive to disa
19b50 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  ble checkpoints-
19b60 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72  on-close, or zer
19b70 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  o (the.** defaul
19b80 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65  t) to enable the
19b90 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20  m, and negative 
19ba0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19bb0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
19bc0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19bd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19be0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
19bf0 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68  er.** into which
19c00 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19c10 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19c20 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e  hether checkpoin
19c30 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68  ts-on-close.** h
19c40 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65  ave been disable
19c50 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72  d - 0 if they ar
19c60 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  e not disabled, 
19c70 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a  1 if they are..*
19c80 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19c90 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19ca0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64  G_ENABLE_QPSG</d
19cb0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  t>.** <dd>^(The 
19cc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19cd0 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69  ENABLE_QPSG opti
19ce0 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
19cf0 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
19d00 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65  he [query planne
19d10 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72  r stability guar
19d20 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20  antee] (QPSG).  
19d30 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73  When the QPSG is
19d40 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69   active,.** a si
19d50 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73  ngle SQL query s
19d60 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c  tatement will al
19d70 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
19d80 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61  e algorithm rega
19d90 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c  rdless.** of val
19da0 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  ues of [bound pa
19db0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65  rameters].)^ The
19dc0 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73   QPSG disables s
19dd0 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  ome query optimi
19de0 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  zations.** that 
19df0 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75  look at the valu
19e00 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61  es of bound para
19e10 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61  meters, which ca
19e20 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72  n make some quer
19e30 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20  ies.** slower.  
19e40 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73  But the QPSG has
19e50 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f   the advantage o
19e60 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62  f more predictab
19e70 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69  le behavior.  Wi
19e80 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61  th.** the QPSG a
19e90 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69  ctive, SQLite wi
19ea0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
19eb0 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61  e same query pla
19ec0 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  n in the field a
19ed0 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75  s.** was used du
19ee0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20  ring testing in 
19ef0 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20  the lab..** The 
19f00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19f10 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
19f20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19f30 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19f40 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c  le .** the QPSG,
19f50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19f60 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67  ble QPSG, or neg
19f70 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19f80 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
19f90 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63  changed. The sec
19fa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19fb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19fc0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19fd0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19fe0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19ff0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65  cate whether the
1a000 20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65   QPSG is disable
1a010 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
1a020 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1a030 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  all..** </dd>.**
1a040 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a050 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1a060 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EQP</dt>.** <dd>
1a070 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
1a080 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41   output of EXPLA
1a090 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f  IN QUERY PLAN co
1a0a0 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20  mmands does not 
1a0b0 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70  .** include outp
1a0c0 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61  ut for any opera
1a0d0 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20  tions performed 
1a0e0 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  by trigger progr
1a0f0 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74  ams. This.** opt
1a100 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73  ion is used to s
1a110 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65  et or clear (the
1a120 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67   default) a flag
1a130 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68   that governs th
1a140 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20  is.** behavior. 
1a150 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1a160 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1a170 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  is operation is 
1a180 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20  an integer -.** 
1a190 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1a1a0 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72  le output for tr
1a1b0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20  igger programs, 
1a1c0 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  or zero to disab
1a1d0 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67  le it,.** or neg
1a1e0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1a1f0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1a200 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
1a210 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a220 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a230 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1a240 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a  ich is written .
1a250 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  ** 0 or 1 to ind
1a260 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75  icate whether ou
1a270 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72  tput-for-trigger
1a280 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62  s has been disab
1a290 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69  led - 0 if .** i
1a2a0 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65  t is not disable
1a2b0 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20  d, 1 if it is.  
1a2c0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1a2d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a2e0 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1a2f0 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  SE</dt>.** <dd> 
1a300 53 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44  Set the SQLITE_D
1a310 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1a320 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20  TABASE flag and 
1a330 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43  then run.** [VAC
1a340 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  UUM] in order to
1a350 20 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73   reset a databas
1a360 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70  e back to an emp
1a370 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77  ty database.** w
1a380 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e  ith no schema an
1a390 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68  d no content. Th
1a3a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63  e following proc
1a3b0 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66  ess works even f
1a3c0 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f  or.** a badly co
1a3d0 72 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65  rrupted database
1a3e0 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   file:.** <ol>.*
1a3f0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1a400 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1a410 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1a420 45 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20  ET_DATABASE, 1, 
1a430 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c  0);.** <li> [sql
1a440 69 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22  ite3_exec](db, "
1a450 5b 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c  [VACUUM]", 0, 0,
1a460 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c   0);.** <li> sql
1a470 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64  ite3_db_config(d
1a480 62 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  b, SQLITE_DBCONF
1a490 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53  IG_RESET_DATABAS
1a4a0 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f  E, 0, 0);.** </o
1a4b0 6c 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65  l>.** Because re
1a4c0 73 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61  setting a databa
1a4d0 73 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76  se is destructiv
1a4e0 65 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62  e and irreversib
1a4f0 6c 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65  le, the.** proce
1a500 73 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20  ss requires the 
1a510 75 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63  use of this obsc
1a520 75 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74  ure API and mult
1a530 69 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65  iple steps to he
1a540 6c 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61  lp.** ensure tha
1a550 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61  t it does not ha
1a560 70 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74  ppen by accident
1a570 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ..** </dd>.** </
1a580 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1a590 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1a5a0 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20  AINDBNAME       
1a5b0 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e       1000 /* con
1a5c0 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66  st char* */.#def
1a5d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1a5e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
1a5f0 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
1a600 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
1a610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a620 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a630 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
1a640 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
1a650 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1a660 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a670 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
1a680 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
1a690 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a6a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a6b0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
1a6c0 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
1a6d0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a6e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a6f0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
1a700 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
1a710 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1a720 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a730 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
1a740 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a  OSE      1006 /*
1a750 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1a760 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1a770 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
1a780 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20             1007 
1a790 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1a7a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a7b0 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1a7c0 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30  QP           100
1a7d0 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  8 /* int int* */
1a7e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a7f0 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1a800 41 54 41 42 41 53 45 20 20 20 20 20 20 20 20 31  ATABASE        1
1a810 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  009 /* int int* 
1a820 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a830 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20  E_DBCONFIG_MAX  
1a840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a850 20 31 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74   1009 /* Largest
1a860 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a   DBCONFIG */../*
1a870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
1a880 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1a890 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
1a8a0 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
1a8b0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a8c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1a8d0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
1a8e0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
1a8f0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1a900 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
1a910 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
1a920 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
1a930 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
1a940 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
1a950 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
1a960 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
1a970 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
1a980 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
1a990 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
1a9a0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
1a9b0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
1a9c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a9d0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
1a9e0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
1a9f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
1aa00 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
1aa10 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
1aa20 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
1aa30 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
1aa40 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
1aa50 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
1aa60 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
1aa70 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
1aa80 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
1aa90 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
1aaa0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
1aab0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
1aac0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
1aad0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
1aae0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
1aaf0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
1ab00 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
1ab10 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
1ab20 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
1ab30 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
1ab40 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
1ab50 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
1ab60 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
1ab70 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
1ab80 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
1ab90 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
1aba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1abb0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1abc0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
1abd0 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
1abe0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
1abf0 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
1ac00 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
1ac10 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
1ac20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
1ac30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
1ac40 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
1ac50 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
1ac60 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
1ac70 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1ac80 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
1ac90 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
1aca0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1acb0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1acc0 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
1acd0 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
1ace0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1acf0 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
1ad00 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1ad10 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
1ad20 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
1ad30 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
1ad40 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
1ad50 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
1ad60 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
1ad70 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
1ad80 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
1ad90 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1ada0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
1adb0 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
1adc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1add0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1ade0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
1adf0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1ae00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
1ae10 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
1ae20 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1ae30 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
1ae40 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
1ae50 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
1ae60 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
1ae70 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
1ae80 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
1ae90 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
1aea0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1aeb0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
1aec0 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
1aed0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1aee0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
1aef0 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
1af00 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
1af10 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
1af20 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
1af30 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1af40 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
1af50 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
1af60 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
1af70 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
1af80 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
1af90 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
1afa0 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
1afb0 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
1afc0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1afd0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
1afe0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
1aff0 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
1b000 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
1b010 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
1b020 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1b030 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
1b040 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
1b050 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
1b060 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1b070 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
1b080 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1b090 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
1b0a0 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
1b0b0 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
1b0c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b0d0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
1b0e0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
1b0f0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
1b100 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
1b110 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
1b120 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
1b130 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
1b140 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
1b150 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
1b160 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
1b170 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
1b180 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1b190 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b1a0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
1b1b0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
1b1c0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
1b1d0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
1b1e0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
1b1f0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
1b200 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
1b210 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
1b220 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1b230 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1b240 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
1b250 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
1b260 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
1b270 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
1b280 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
1b290 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
1b2a0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
1b2b0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
1b2c0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
1b2d0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
1b2e0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
1b2f0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
1b300 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
1b310 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
1b320 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
1b330 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
1b340 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1b350 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
1b360 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
1b370 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1b380 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
1b390 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
1b3a0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
1b3b0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
1b3c0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
1b3d0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
1b3e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1b3f0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
1b400 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1b410 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
1b420 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b430 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1b440 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1b450 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1b460 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1b470 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1b480 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1b490 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1b4a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1b4b0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1b4c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1b4d0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1b4e0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1b4f0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1b500 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1b510 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1b520 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1b530 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1b540 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1b550 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1b560 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1b570 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1b580 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1b590 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
1b5a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1b5b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b5c0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1b5d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b5e0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1b5f0 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1b600 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b610 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1b620 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1b630 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1b640 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1b650 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1b660 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1b670 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1b680 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1b690 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b6a0 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1b6b0 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1b6c0 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1b6d0 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
1b6e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1b6f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1b700 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
1b710 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
1b720 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1b730 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1b740 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1b750 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b760 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1b770 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1b780 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1b790 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1b7a0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1b7b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b7c0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1b7d0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b7e0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1b7f0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1b800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1b810 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1b820 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1b830 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1b840 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1b850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1b860 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1b870 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1b880 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1b890 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1b8a0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1b8b0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1b8c0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1b8d0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1b8e0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1b8f0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1b900 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1b910 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1b920 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1b930 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1b940 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1b950 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1b960 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1b970 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1b980 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1b990 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1b9a0 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1b9b0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1b9c0 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1b9d0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1b9e0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1b9f0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1ba00 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ba10 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1ba20 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1ba30 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1ba40 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1ba50 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1ba60 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1ba70 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1ba80 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1ba90 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1baa0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1bab0 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1bac0 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1bad0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1bae0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1baf0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1bb00 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1bb10 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1bb20 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1bb30 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1bb40 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1bb50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1bb60 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1bb70 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1bb80 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1bb90 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1bba0 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1bbb0 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1bbc0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1bbd0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1bbe0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1bbf0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1bc00 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1bc10 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1bc20 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1bc30 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1bc40 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1bc50 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1bc60 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1bc70 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1bc80 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1bc90 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1bca0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1bcb0 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1bcc0 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1bcd0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1bce0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1bcf0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1bd00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1bd10 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1bd20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1bd30 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1bd40 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1bd50 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1bd60 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1bd70 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1bd80 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1bd90 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1bda0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1bdb0 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1bdc0 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1bdd0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1bde0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1bdf0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1be00 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1be10 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1be20 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1be30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1be40 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1be50 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1be60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1be70 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1be80 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1be90 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1bea0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1beb0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1bec0 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1bed0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1bee0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1bef0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1bf00 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1bf10 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1bf20 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1bf30 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1bf40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1bf50 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1bf60 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1bf70 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1bf80 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1bf90 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1bfa0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1bfb0 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1bfc0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1bfd0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1bfe0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1bff0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1c000 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1c010 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1c020 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1c030 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1c040 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1c050 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1c060 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1c070 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1c080 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1c090 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1c0a0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1c0b0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1c0c0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1c0d0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1c0e0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1c0f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1c100 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1c110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c120 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1c130 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1c140 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c150 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1c160 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c170 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1c180 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1c190 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1c1a0 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1c1b0 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1c1c0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1c1d0 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1c1e0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1c1f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c200 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1c210 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1c220 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1c230 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1c240 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1c250 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1c260 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1c270 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1c280 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1c290 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1c2a0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c2b0 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1c2c0 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1c2d0 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1c2e0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1c2f0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1c300 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1c310 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1c320 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1c330 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1c340 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1c350 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1c360 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1c370 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1c380 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1c390 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1c3a0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1c3b0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1c3c0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1c3d0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1c3e0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1c3f0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1c400 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1c410 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1c420 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1c430 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1c440 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1c450 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1c460 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1c470 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1c480 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1c490 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1c4a0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1c4b0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1c4c0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1c4d0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1c4e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1c4f0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1c500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1c510 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1c520 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1c530 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c540 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1c550 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1c560 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1c570 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1c580 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1c590 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1c5a0 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1c5b0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1c5c0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1c5d0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1c5e0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1c5f0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1c600 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1c610 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1c620 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1c630 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1c640 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1c650 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1c660 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1c670 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1c680 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1c690 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1c6a0 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1c6b0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1c6c0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1c6d0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1c6e0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1c6f0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1c700 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1c710 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1c720 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1c730 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1c740 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1c750 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c760 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1c770 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1c780 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1c790 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1c7a0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1c7b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1c7c0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1c7d0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1c7e0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1c7f0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1c800 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1c810 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1c820 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1c830 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1c840 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1c850 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1c860 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c870 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1c880 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1c890 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1c8a0 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1c8b0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1c8c0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1c8d0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1c8e0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1c8f0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1c900 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1c910 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1c920 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1c930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c940 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1c950 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1c960 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1c970 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1c980 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1c990 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c9a0 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1c9b0 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1c9c0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c9d0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c9e0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1c9f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1ca00 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1ca10 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1ca20 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1ca30 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1ca40 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1ca50 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1ca60 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1ca70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ca80 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1ca90 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1caa0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1cab0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1cac0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1cad0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1cae0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1caf0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1cb00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1cb10 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1cb20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1cb30 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1cb40 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1cb50 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1cb60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1cb70 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1cb80 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1cb90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1cba0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1cbb0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1cbc0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1cbd0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f  call returns..*/
1cbe0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
1cbf0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1cc00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cc10 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1cc20 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1cc30 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1cc40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1cc50 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1cc60 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1cc70 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1cc80 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1cc90 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1cca0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1ccb0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1ccc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1ccd0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1cce0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1ccf0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1cd00 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1cd10 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1cd20 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1cd30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1cd40 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1cd50 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1cd60 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1cd70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1cd80 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1cd90 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1cda0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1cdb0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1cdc0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1cdd0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1cde0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1cdf0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1ce00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1ce10 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1ce20 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1ce30 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1ce40 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1ce50 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1ce60 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1ce70 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1ce80 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1ce90 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1cea0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1ceb0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1cec0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1ced0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1cee0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1cef0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1cf00 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1cf10 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1cf20 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1cf30 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1cf40 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1cf50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1cf60 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1cf70 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1cf80 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1cf90 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1cfa0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1cfb0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1cfc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1cfd0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1cfe0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1cff0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1d000 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1d010 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1d020 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1d030 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1d040 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1d050 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1d060 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1d070 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1d080 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1d090 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1d0a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1d0b0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1d0c0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1d0d0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1d0e0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1d0f0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1d100 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1d110 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1d120 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1d130 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1d140 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1d150 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1d160 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1d170 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1d180 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1d190 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1d1a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1d1b0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1d1c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1d1d0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1d1e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1d1f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1d200 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1d210 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1d220 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1d230 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1d240 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
1d250 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1d260 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1d270 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
1d280 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1d290 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1d2a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d2b0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1d2c0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1d2d0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1d2e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1d2f0 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1d300 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1d310 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1d320 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1d330 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1d340 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1d350 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1d360 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d370 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1d380 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1d390 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1d3a0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1d3b0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1d3c0 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1d3d0 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1d3e0 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1d3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1d400 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1d410 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1d420 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1d430 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1d440 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d450 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1d460 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1d470 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1d480 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1d490 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1d4a0 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1d4b0 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1d4c0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1d4d0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1d4e0 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1d4f0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1d500 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1d510 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1d520 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1d530 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1d540 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1d550 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1d560 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1d570 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1d580 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1d590 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1d5a0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1d5b0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1d5c0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1d5d0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1d5e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1d5f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1d600 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1d610 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1d620 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1d630 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1d640 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1d650 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1d660 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1d670 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1d680 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1d690 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1d6a0 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1d6b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d6c0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1d6d0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1d6e0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1d6f0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1d700 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1d710 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1d720 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1d730 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1d740 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d750 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1d760 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1d770 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1d780 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1d790 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1d7a0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1d7b0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1d7c0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1d7d0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1d7e0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1d7f0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1d800 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1d810 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1d820 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1d830 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1d840 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1d850 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1d860 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1d870 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1d880 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1d890 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1d8a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d8b0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1d8c0 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1d8d0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1d8e0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1d8f0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1d900 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1d910 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1d920 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1d930 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1d940 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1d950 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1d960 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1d970 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1d980 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1d990 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1d9a0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1d9b0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1d9c0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1d9d0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1d9e0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1d9f0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1da00 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1da10 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1da20 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1da30 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1da40 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1da50 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1da60 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1da70 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1da80 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1da90 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1daa0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1dab0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1dac0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1dad0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1dae0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1daf0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1db00 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1db10 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1db20 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1db30 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1db40 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1db50 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1db60 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1db70 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1db80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1db90 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1dba0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1dbb0 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1dbc0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1dbd0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1dbe0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1dbf0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1dc00 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1dc10 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1dc20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1dc30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1dc40 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1dc50 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1dc60 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1dc70 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1dc80 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1dc90 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1dca0 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1dcb0 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1dcc0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1dcd0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1dce0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1dcf0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1dd00 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1dd10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd20 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1dd30 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1dd40 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1dd50 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1dd60 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1dd70 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1dd80 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1dd90 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1dda0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1ddb0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1ddc0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1ddd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1dde0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1ddf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1de00 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1de10 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1de20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1de30 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1de40 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1de50 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1de60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1de70 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1de80 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1de90 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1dea0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1deb0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1dec0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1ded0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1dee0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1def0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1df00 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1df10 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1df20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1df30 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1df40 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1df50 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1df60 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1df70 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1df80 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1df90 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1dfa0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1dfb0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1dfc0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1dfd0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1dfe0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1dff0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1e000 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1e010 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1e020 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1e030 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1e040 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1e050 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1e060 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1e070 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1e080 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1e090 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1e0a0 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1e0b0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1e0c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e0d0 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1e0e0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1e0f0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1e100 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1e110 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1e120 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1e130 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1e140 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1e150 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1e160 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1e170 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1e180 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1e190 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1e1a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1e1b0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1e1c0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1e1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1e1e0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1e1f0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1e200 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1e210 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1e220 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1e230 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1e240 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1e250 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1e260 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1e270 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1e280 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1e290 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1e2a0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1e2b0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1e2c0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1e2d0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1e2e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1e2f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1e300 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1e310 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1e320 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1e330 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1e340 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1e350 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1e360 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1e370 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1e380 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1e390 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1e3a0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1e3b0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1e3c0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1e3d0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1e3e0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1e3f0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1e400 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1e410 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1e420 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1e430 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1e440 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1e450 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1e460 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1e470 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1e480 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1e490 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1e4a0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1e4b0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1e4c0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1e4d0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1e4e0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1e4f0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1e500 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1e510 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1e520 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1e530 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1e540 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1e550 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1e560 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1e570 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1e580 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1e590 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1e5a0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1e5b0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1e5c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1e5d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1e5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1e5f0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1e600 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1e610 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1e620 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1e630 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1e640 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1e650 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1e660 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1e670 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e680 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1e690 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1e6a0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1e6b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1e6c0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1e6d0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1e6e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1e6f0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1e700 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1e710 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1e720 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e730 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e740 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1e750 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1e760 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1e770 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1e780 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1e790 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1e7a0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1e7b0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1e7c0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1e7d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e7e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1e7f0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1e800 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1e810 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1e820 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1e830 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1e840 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1e850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1e860 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1e870 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1e880 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1e890 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1e8a0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1e8b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e8c0 3e 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 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1e8e0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1e8f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1e900 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1e910 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1e920 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1e930 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e940 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1e950 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e960 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1e970 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e980 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1e990 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1e9a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1e9b0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1e9c0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e9d0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1e9e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e9f0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1ea00 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ea10 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1ea20 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1ea30 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1ea40 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1ea50 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1ea60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ea70 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1ea80 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1ea90 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1eaa0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1eab0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1eac0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1ead0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1eae0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1eaf0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1eb00 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1eb10 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1eb20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1eb30 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1eb40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1eb50 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1eb60 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1eb70 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1eb80 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1eb90 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1eba0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1ebb0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1ebc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1ebd0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1ebe0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1ebf0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1ec00 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1ec10 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1ec20 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1ec30 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1ec40 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1ec50 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ec60 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1ec70 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1ec80 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1ec90 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1eca0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ecb0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1ecc0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1ecd0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1ece0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1ecf0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1ed00 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1ed10 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1ed20 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1ed30 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1ed40 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1ed50 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1ed60 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1ed70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ed80 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1ed90 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1eda0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1edb0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1edc0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1edd0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ede0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1edf0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ee00 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ee10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1ee20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1ee30 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1ee40 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1ee50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ee60 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1ee70 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ee80 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1ee90 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1eea0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1eeb0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1eec0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1eed0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1eee0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1eef0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1ef00 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1ef10 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1ef20 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1ef30 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1ef40 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1ef50 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1ef60 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1ef70 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1ef80 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1ef90 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1efa0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1efb0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1efc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1efd0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1efe0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1eff0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1f000 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1f010 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1f020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1f030 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1f040 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1f050 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1f060 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1f070 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1f080 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1f090 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1f0a0 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1f0b0 6d 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  mon formatting o
1f0c0 70 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74  ptions from.** t
1f0d0 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
1f0e0 61 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a  ary printf() .**
1f0f0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1f100 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1f110 72 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d  rd formats ([%q]
1f120 2c 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e  , [%Q], [%w], an
1f130 64 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20  d [%z])..** See 
1f140 74 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  the [built-in pr
1f150 69 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74  intf()] document
1f160 61 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c  ation for detail
1f170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1f180 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1f190 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1f1a0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1f1b0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1f1c0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1f1d0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1f1e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f1f0 36 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  64()]..** The st
1f200 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1f210 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1f220 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1f230 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1f240 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1f250 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1f260 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1f270 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1f280 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d  ite3_malloc64()]
1f290 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1f2a0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1f2b0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1f2c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1f2d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1f2e0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1f2f0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1f300 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1f310 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1f320 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1f330 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1f340 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1f350 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1f360 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1f370 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f380 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1f390 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1f3a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1f3b0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1f3c0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1f3d0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1f3e0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1f3f0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1f400 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1f410 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1f420 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1f430 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1f440 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1f450 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1f460 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1f470 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1f480 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1f490 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f4a0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1f4b0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1f4c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1f4d0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1f4e0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1f4f0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1f500 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1f510 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1f520 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1f530 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1f540 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1f550 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1f560 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1f570 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f580 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f590 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1f5a0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1f5b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1f5c0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1f5d0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1f5e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1f5f0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1f600 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1f610 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1f620 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1f630 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1f640 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1f650 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1f660 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1f670 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1f680 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1f690 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1f6a0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1f6b0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1f6c0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1f6d0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1f6e0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1f6f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1f700 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1f710 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1f720 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1f730 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1f740 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1f750 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62  ** See also:  [b
1f760 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1f770 5d 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c  ], [printf() SQL
1f780 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68   function].*/.ch
1f790 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1f7a0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1f7b0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1f7c0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1f7d0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1f7e0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1f7f0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1f800 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f810 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1f820 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1f830 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f840 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f860 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1f870 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1f880 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1f890 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1f8a0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1f8b0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1f8c0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1f8d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1f8e0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1f8f0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1f900 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1f910 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1f920 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1f930 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1f940 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1f950 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1f960 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1f970 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1f980 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1f990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f9a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1f9b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1f9c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1f9d0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1f9e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1f9f0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1fa00 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1fa10 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1fa20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1fa30 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1fa40 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1fa50 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1fa60 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1fa70 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1fa80 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1fa90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1faa0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1fab0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1fac0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1fad0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1fae0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1faf0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1fb00 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1fb10 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1fb20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1fb30 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1fb40 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1fb50 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1fb60 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1fb70 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1fb80 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1fb90 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1fba0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1fbb0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1fbc0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1fbd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1fbe0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1fbf0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1fc00 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1fc10 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1fc20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1fc30 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1fc40 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1fc50 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1fc60 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1fc70 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1fc80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1fc90 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1fca0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1fcb0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1fcc0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1fcd0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1fce0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1fcf0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1fd00 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1fd10 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1fd20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1fd30 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1fd40 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fd50 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1fd60 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1fd70 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1fd80 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1fd90 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1fda0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1fdb0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1fdc0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1fdd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1fde0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1fdf0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1fe00 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1fe10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1fe20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1fe30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fe40 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1fe50 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1fe60 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1fe70 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1fe80 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1fe90 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1fea0 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1feb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fec0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1fed0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1fee0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1fef0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ff00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1ff10 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1ff20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1ff30 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1ff40 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1ff50 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1ff60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ff70 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ff80 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ff90 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ffa0 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ffb0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ffc0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ffd0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ffe0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1fff0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
20000 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
20010 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
20020 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
20030 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
20040 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
20050 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
20060 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
20070 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
20080 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
20090 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
200a0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
200b0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
200c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
200d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
200e0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
200f0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
20100 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
20110 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
20120 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
20130 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
20140 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
20150 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
20160 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
20170 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
20180 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
20190 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
201a0 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
201b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
201c0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
201d0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
201e0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
201f0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
20200 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
20210 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
20220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20230 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
20240 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
20250 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
20260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
20270 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20280 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
20290 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
202a0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
202b0 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
202c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
202d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
202e0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
202f0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20300 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
20310 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
20320 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
20330 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
20340 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
20350 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
20360 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
20370 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
20380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
20390 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
203a0 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
203b0 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
203c0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
203d0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
203e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
203f0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
20400 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
20410 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
20420 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
20430 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
20440 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
20450 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
20460 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
20470 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
20480 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
20490 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
204a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
204b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
204c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
204d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
204e0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
204f0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
20500 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
20510 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
20520 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
20530 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
20540 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
20550 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
20560 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
20570 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
20580 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
20590 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
205a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
205b0 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
205c0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
205d0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
205e0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
205f0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
20600 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
20610 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
20620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20630 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
20640 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
20650 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
20660 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
20670 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
20680 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
20690 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
206a0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
206b0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
206c0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
206d0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
206e0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
206f0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
20700 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
20710 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
20720 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
20730 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
20740 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
20750 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
20760 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
20770 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
20780 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
20790 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
207a0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
207b0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
207c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
207d0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
207e0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
207f0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
20800 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
20810 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
20820 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
20830 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
20840 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
20850 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
20860 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
20870 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
20880 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20890 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
208a0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
208b0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
208c0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
208d0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
208e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
208f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20900 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
20910 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
20920 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
20930 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
20940 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
20950 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
20960 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
20970 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
20980 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
20990 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
209a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
209b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
209c0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
209d0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
209e0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
209f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
20a00 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
20a10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
20a20 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
20a30 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
20a40 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
20a50 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
20a60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
20a70 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
20a80 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
20a90 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
20aa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20ab0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
20ac0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
20ad0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
20ae0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
20af0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
20b00 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
20b10 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
20b20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20b30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
20b40 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
20b50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
20b60 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
20b70 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
20b80 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
20b90 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
20ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
20bb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20bc0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20bd0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
20be0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
20bf0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
20c00 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
20c10 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
20c20 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
20c30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20c40 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
20c50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
20c60 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
20c70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20c80 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
20c90 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
20ca0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
20cb0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
20cc0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
20cd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
20ce0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
20cf0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20d00 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
20d10 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
20d20 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
20d30 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
20d40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
20d50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
20d60 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
20d70 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
20d80 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
20d90 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
20da0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
20db0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20dc0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
20dd0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
20de0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
20df0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
20e00 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
20e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
20e20 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
20e30 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
20e40 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
20e50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20e60 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
20e70 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
20e80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
20e90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
20ea0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
20eb0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
20ec0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
20ed0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
20ee0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
20ef0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20f00 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
20f10 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
20f20 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
20f30 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
20f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
20f50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
20f60 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
20f70 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
20f80 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
20f90 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
20fa0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
20fb0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
20fc0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
20fd0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
20fe0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
20ff0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
21000 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
21010 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
21020 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
21030 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
21040 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
21050 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
21060 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
21070 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
21080 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
21090 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
210a0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
210b0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
210c0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
210d0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
210e0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
210f0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
21100 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
21110 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
21120 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
21130 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
21140 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
21150 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
21160 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
21170 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
21180 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
21190 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
211a0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
211b0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
211c0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
211d0 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
211e0 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
211f0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
21200 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
21210 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
21220 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
21230 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
21240 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
21250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
21260 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
21270 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
21280 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
21290 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
212a0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
212b0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
212c0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
212d0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
212e0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
212f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
21300 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
21310 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
21320 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
21330 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
21340 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
21350 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
21360 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
21370 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
21380 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
21390 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
213a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
213b0 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  k}.**.** ^This r
213c0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
213d0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
213e0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
213f0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
21400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21410 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
21420 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
21430 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
21440 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21450 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
21460 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
21470 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
21480 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
21490 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
214a0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
214b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
214c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
214d0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
214e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
214f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
21500 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a  pare16_v2()],.**
21510 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
21520 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20  epare16_v3()].  
21530 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
21540 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
21550 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
21560 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
21570 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
21580 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
21590 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
215a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
215b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
215c0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
215d0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
215e0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
215f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21600 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
21610 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21620 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
21630 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
21640 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
21650 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
21660 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
21670 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
21680 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
21690 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
216a0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
216b0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
216c0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
216d0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
216e0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
216f0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
21700 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21710 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
21720 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
21730 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
21740 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
21750 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
21760 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
21770 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21780 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21790 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
217a0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
217b0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
217c0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
217d0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
217e0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
217f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21800 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
21810 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
21820 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
21830 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
21840 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21850 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
21860 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21870 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21880 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21890 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
218a0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
218b0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
218c0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
218d0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
218e0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
218f0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
21900 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
21910 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
21920 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21930 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
21940 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
21950 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
21960 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21970 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
21980 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21990 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
219a0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
219b0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
219c0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
219d0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
219e0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
219f0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
21a00 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
21a10 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
21a20 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
21a30 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
21a40 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c  k are either NUL
21a50 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65  L pointers or ze
21a60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
21a70 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f  rings.** that co
21a80 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
21a90 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
21aa0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
21ab0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41  authorized..** A
21ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
21ad0 20 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61   always be prepa
21ae0 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72  red to encounter
21af0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21b00 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  in any.** of the
21b10 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74   third through t
21b20 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
21b30 65 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f  ers of the autho
21b40 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63  rization callbac
21b50 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  k..**.** ^If the
21b60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
21b70 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
21b80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21b90 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21ba0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21bb0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
21bc0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
21bd0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
21be0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
21bf0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
21c00 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
21c10 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
21c20 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
21c30 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
21c40 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
21c50 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
21c60 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
21c70 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
21c80 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
21c90 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
21ca0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
21cb0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
21cc0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
21cd0 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20  * ^When a table 
21ce0 69 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  is referenced by
21cf0 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20   a [SELECT] but 
21d00 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  no column values
21d10 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65   are.** extracte
21d20 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c  d from that tabl
21d30 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69  e (for example i
21d40 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a  n a query like.*
21d50 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28  * "SELECT count(
21d60 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68  *) FROM tab") th
21d70 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52  en the [SQLITE_R
21d80 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20  EAD] authorizer 
21d90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69  callback.** is i
21da0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
21db0 74 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20  that table with 
21dc0 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68  a column name th
21dd0 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  at is an empty s
21de0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
21df0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21e00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
21e10 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21e20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
21e30 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21e40 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
21e50 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
21e60 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
21e70 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
21e80 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
21e90 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
21ea0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
21eb0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
21ec0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
21ed0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
21ee0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21ef0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
21f00 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
21f10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
21f20 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
21f30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21f40 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
21f50 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
21f60 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
21f70 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
21f80 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
21f90 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
21fa0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
21fb0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
21fc0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
21fd0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
21fe0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
21ff0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
22000 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
22010 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
22020 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
22030 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
22040 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
22050 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
22060 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
22070 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
22080 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
22090 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
220a0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
220b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
220c0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
220d0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
220e0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
220f0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
22100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
22110 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
22120 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
22130 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
22140 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
22150 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
22160 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
22170 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
22180 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
22190 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
221a0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
221b0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
221c0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
221d0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
221e0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
221f0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
22200 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
22210 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
22220 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
22230 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
22240 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
22250 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
22260 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
22270 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
22280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22290 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
222a0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
222b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
222c0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
222d0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
222e0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
222f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22300 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
22310 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
22320 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
22330 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
22340 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
22350 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22360 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
22370 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
22380 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
22390 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
223a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
223b0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
223c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
223d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
223e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
223f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
22400 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
22410 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
22420 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
22430 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
22440 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
22450 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
22460 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
22470 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22480 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
22490 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
224a0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
224b0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
224c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
224d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
224e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
224f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
22500 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
22510 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
22520 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
22530 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
22540 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
22550 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
22560 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
22570 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
22580 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
22590 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
225a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
225b0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
225c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
225d0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
225e0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
225f0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
22600 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
22610 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
22620 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
22630 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
22640 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
22650 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
22660 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
22670 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
22680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22690 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
226a0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
226b0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
226c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
226d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
226e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
226f0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
22700 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
22710 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
22720 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
22730 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
22740 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
22750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
22760 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
22770 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
22780 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22790 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
227a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
227b0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
227c0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
227d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
227e0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
227f0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
22800 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
22810 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
22820 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
22830 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
22840 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
22850 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
22860 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
22870 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
22880 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22890 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
228a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
228b0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
228c0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
228d0 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
228e0 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
228f0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
22900 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
22910 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
22920 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
22930 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
22940 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
22950 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
22960 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
22970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
22980 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
22990 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
229a0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
229b0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
229c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
229d0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
229e0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
229f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22a00 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
22a10 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
22a20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
22a30 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
22a40 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
22a50 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
22a60 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
22a70 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
22a80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
22a90 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
22aa0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
22ab0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
22ac0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
22ad0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
22ae0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
22af0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
22b00 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
22b10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22b20 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
22b30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
22b40 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
22b50 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
22b60 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
22b70 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
22b80 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
22b90 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
22ba0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
22bb0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
22bc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22bd0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
22be0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
22bf0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
22c00 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
22c10 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
22c20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22c30 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
22c40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
22c50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22c60 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
22c70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
22c80 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
22c90 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
22ca0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
22cb0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
22cc0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
22cd0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
22ce0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22cf0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
22d00 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
22d10 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
22d20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
22d30 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
22d40 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
22d50 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
22d60 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
22d70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
22d80 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
22d90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22db0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
22dc0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
22dd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22de0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
22df0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
22e00 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22e10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22e20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22e30 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
22e40 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
22e50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22e60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22e80 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
22e90 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
22ea0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22eb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22ed0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
22ee0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
22ef0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22f00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22f10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22f20 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
22f30 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
22f40 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22f50 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22f70 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
22f80 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
22f90 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22fa0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22fc0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
22fd0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
22fe0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22ff0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23000 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23010 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
23020 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
23030 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
23040 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23050 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
23060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23070 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
23080 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23090 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
230a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
230b0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
230c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
230d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
230e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
230f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
23100 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
23110 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23120 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23140 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
23150 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
23160 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
23170 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23190 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
231a0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
231b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
231c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
231d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
231e0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
231f0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
23200 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
23210 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23230 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
23240 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
23250 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
23260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23280 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
23290 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
232a0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
232b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
232c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
232d0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
232e0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
232f0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
23300 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23320 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
23330 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
23340 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
23350 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23370 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
23380 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
23390 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
233a0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
233b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
233c0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
233d0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
233e0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
233f0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
23400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
23410 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
23420 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
23430 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
23440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
23460 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
23470 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
23480 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
23490 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
234a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
234b0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
234c0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
234d0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
234e0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
234f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
23500 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23510 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
23520 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
23530 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23540 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
23550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23560 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
23570 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
23580 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23590 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
235a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
235b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
235c0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
235d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
235e0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
235f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
23600 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
23610 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23630 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
23640 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
23650 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23680 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
23690 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
236a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
236b0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
236c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
236d0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
236e0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
236f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23700 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
23710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23720 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
23730 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
23740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23750 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
23760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23770 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
23780 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
23790 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
237a0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
237b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
237c0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
237d0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
237e0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
237f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23800 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
23810 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
23820 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
23830 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23850 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
23860 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
23870 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23880 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
23890 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70  routines are dep
238a0 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65  recated. Use the
238b0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
238c0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  v2()] interface.
238d0 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ** instead of th
238e0 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72  e routines descr
238f0 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ibed here..**.**
23900 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23910 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
23920 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
23930 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
23940 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
23950 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
23960 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
23970 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
23980 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23990 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
239a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
239b0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
239c0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
239d0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
239e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
239f0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
23a00 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
23a10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
23a20 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
23a30 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
23a40 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
23a50 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
23a60 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
23a70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
23a80 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
23a90 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
23aa0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
23ab0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
23ac0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
23ad0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
23ae0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
23af0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
23b00 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
23b10 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
23b20 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
23b30 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
23b40 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
23b50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
23b60 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
23b70 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
23b80 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
23b90 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
23ba0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
23bb0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
23bc0 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
23bd0 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
23be0 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
23bf0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
23c00 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
23c10 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
23c20 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
23c30 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
23c40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
23c50 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
23c60 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
23c70 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
23c80 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23c90 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
23ca0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
23cb0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
23cc0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
23cd0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
23ce0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
23cf0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
23d00 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
23d10 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
23d20 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
23d30 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
23d40 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
23d50 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
23d60 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
23d70 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
23d80 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
23d90 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
23da0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
23db0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
23dc0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
23dd0 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
23de0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
23df0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
23e00 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
23e10 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
23e20 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
23e30 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
23e40 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
23e50 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
23e60 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
23e70 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23e80 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
23e90 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
23ea0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
23eb0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
23ec0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
23ed0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
23ee0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
23ef0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23f00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
23f10 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
23f20 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
23f30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
23f40 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
23f50 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
23f60 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
23f70 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
23f80 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
23f90 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
23fa0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
23fb0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
23fc0 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
23fd0 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
23fe0 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
23ff0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
24000 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
24010 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a  The M argument.*
24020 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  * to [sqlite3_tr
24030 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d  ace_v2(D,M,X,P)]
24040 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
24050 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
24060 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
24070 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
24080 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
24090 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
240a0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
240b0 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
240c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
240d0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
240e0 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
240f0 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
24100 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
24110 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
24120 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
24130 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
24140 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
24150 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
24160 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
24170 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
24180 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
24190 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
241a0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
241b0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
241c0 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
241d0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
241e0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
241f0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
24200 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
24210 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
24220 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
24230 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
24240 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
24250 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
24260 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
24270 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
24280 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24290 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
242a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
242b0 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
242c0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
242d0 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
242e0 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
242f0 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
24300 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
24310 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
24320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24330 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
24340 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
24350 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
24360 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
24370 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24380 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
24390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
243a0 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
243b0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
243c0 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
243d0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
243e0 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
243f0 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
24400 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
24410 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
24420 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
24430 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
24440 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
24450 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
24460 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
24470 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
24480 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
24490 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
244a0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
244b0 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
244c0 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
244d0 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
244e0 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
244f0 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
24500 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
24510 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
24520 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
24530 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
24540 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
24550 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
24560 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
24570 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
24580 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
24590 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
245a0 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
245b0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
245c0 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
245d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
245e0 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
245f0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
24600 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
24610 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
24620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
24630 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
24640 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
24650 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
24660 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
24670 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
24680 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
24690 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
246a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
246b0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
246c0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
246d0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
246e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
246f0 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
24700 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
24710 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
24720 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
24730 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
24740 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24750 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
24760 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24770 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
24780 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
24790 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
247a0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
247b0 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
247c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
247d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
247e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
247f0 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
24800 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
24810 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
24820 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
24830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
24840 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
24850 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
24860 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
24870 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24880 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
24890 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
248a0 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
248b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
248c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
248d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
248e0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
248f0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
24900 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
24910 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
24920 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
24930 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
24940 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
24950 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
24960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
24970 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
24980 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
24990 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
249a0 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
249b0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
249c0 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
249d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
249e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
249f0 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
24a00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
24a10 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
24a20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
24a30 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
24a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24a50 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
24a60 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
24a70 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
24a80 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
24a90 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
24aa0 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
24ab0 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
24ac0 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
24ad0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
24ae0 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
24af0 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
24b00 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
24b10 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
24b20 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
24b30 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
24b40 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
24b50 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
24b60 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
24b70 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24b80 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
24b90 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
24ba0 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
24bb0 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
24bc0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
24bd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
24be0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24bf0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
24c00 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
24c10 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
24c20 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
24c30 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
24c40 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
24c50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
24c60 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
24c70 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
24c80 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
24c90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
24ca0 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
24cb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
24cc0 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
24cd0 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
24ce0 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
24cf0 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
24d00 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24d10 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
24d20 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
24d30 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
24d40 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
24d50 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
24d60 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
24d70 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
24d80 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
24d90 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
24da0 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
24db0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
24dc0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
24dd0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
24de0 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
24df0 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
24e00 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
24e10 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
24e20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
24e30 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
24e40 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
24e50 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
24e60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
24e70 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
24e80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24e90 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
24ea0 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
24eb0 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
24ec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
24ed0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
24ee0 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
24ef0 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
24f00 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
24f10 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
24f20 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
24f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24f40 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
24f50 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
24f60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
24f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24f80 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24f90 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
24fa0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
24fb0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
24fc0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
24fd0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
24fe0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
24ff0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
25000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
25010 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
25020 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
25030 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
25040 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
25050 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
25060 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
25070 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
25080 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
25090 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
250a0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
250b0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
250c0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
250d0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
250e0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
250f0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
25100 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
25110 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
25120 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
25130 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
25140 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
25150 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
25160 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
25170 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
25180 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
25190 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
251a0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
251b0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
251c0 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
251d0 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
251e0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
251f0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
25200 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
25210 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
25220 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
25230 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
25240 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
25250 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
25260 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
25270 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
25280 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
25290 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
252a0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
252b0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
252c0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
252d0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
252e0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
252f0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
25300 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
25310 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
25320 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
25330 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
25340 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
25350 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
25360 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
25370 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
25380 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
25390 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
253a0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
253b0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
253c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
253d0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
253e0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
253f0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
25400 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
25410 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25420 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
25430 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
25440 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
25450 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
25460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
25470 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25480 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
25490 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
254a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
254b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
254c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
254d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
254e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
254f0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
25500 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
25510 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
25520 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
25530 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
25540 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
25550 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
25560 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
25570 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
25580 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
25590 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
255a0 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
255b0 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
255c0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
255d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
255e0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
255f0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
25600 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
25610 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
25620 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
25630 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
25640 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
25650 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
25660 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
25670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25680 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
25690 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
256a0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
256b0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
256c0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
256d0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
256e0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
256f0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
25700 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
25710 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
25720 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
25730 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
25740 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
25750 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
25760 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
25770 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
25780 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
25790 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
257a0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
257b0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
257c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
257d0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
257e0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
257f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
25800 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
25810 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
25820 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
25830 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
25840 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
25850 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
25860 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
25870 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
25880 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
25890 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
258a0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
258b0 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
258c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
258d0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
258e0 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
258f0 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
25900 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
25910 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
25920 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25930 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
25940 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
25950 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
25960 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
25970 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
25980 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
25990 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
259a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
259b0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
259c0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
259d0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
259e0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
259f0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
25a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25a10 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
25a20 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
25a30 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
25a40 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
25a50 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
25a60 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
25a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25a80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
25a90 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
25aa0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
25ab0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
25ac0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
25ad0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
25ae0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
25af0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
25b00 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
25b10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25b20 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
25b30 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
25b40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25b50 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
25b60 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
25b70 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
25b80 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
25b90 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
25ba0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
25bb0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
25bc0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
25bd0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
25be0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
25bf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
25c00 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
25c10 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
25c20 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
25c30 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
25c40 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
25c50 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
25c60 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
25c70 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
25c80 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
25c90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
25ca0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
25cb0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
25cc0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
25cd0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
25ce0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
25cf0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
25d00 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25d10 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25d20 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
25d30 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
25d40 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
25d50 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
25d60 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
25d70 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
25d80 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
25d90 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
25da0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
25db0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
25dc0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
25dd0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25de0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
25df0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
25e00 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
25e10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25e20 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
25e30 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
25e40 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
25e50 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
25e60 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
25e70 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
25e80 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
25e90 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
25ea0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
25eb0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
25ec0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
25ed0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
25ee0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
25ef0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
25f00 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
25f10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25f20 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
25f30 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
25f40 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
25f50 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
25f60 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
25f70 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
25f80 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
25f90 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
25fa0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
25fb0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
25fc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
25fd0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
25fe0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
25ff0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
26000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26010 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
26020 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
26030 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
26040 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
26050 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
26060 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
26070 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
26080 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
26090 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
260a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
260b0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
260c0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
260d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
260e0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
260f0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
26100 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
26110 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
26120 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
26130 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
26140 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
26150 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
26160 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
26170 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
26180 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
26190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
261a0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
261b0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
261c0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
261d0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
261e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
261f0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
26200 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
26210 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
26220 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
26230 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
26240 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26250 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26270 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
26280 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
26290 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
262a0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
262b0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
262c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
262d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
262e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
262f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
26300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
26310 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
26320 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
26330 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
26340 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
26350 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
26360 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
26370 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
26380 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
26390 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
263a0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
263b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
263c0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
263d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
263e0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
263f0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
26400 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
26410 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
26420 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
26430 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
26440 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
26450 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
26460 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
26470 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
26480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
26490 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
264a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
264b0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
264c0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
264d0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
264e0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
264f0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
26500 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
26510 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
26520 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
26530 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
26540 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
26550 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
26560 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
26570 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
26580 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
26590 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
265a0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
265b0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
265c0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
265d0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
265e0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
265f0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
26600 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
26610 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
26620 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
26630 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
26640 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
26650 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
26660 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
26670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26680 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
26690 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
266a0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
266b0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
266c0 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
266d0 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
266e0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
266f0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
26700 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
26710 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
26720 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
26730 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
26740 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
26750 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
26760 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
26770 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
26780 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
26790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
267a0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
267b0 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67  in the third arg
267c0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
267d0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
267e0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
267f0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
26800 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
26810 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
26820 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
26830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
26840 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
26850 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
26860 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
26870 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
26880 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
26890 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
268a0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
268b0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
268c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
268d0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
268e0 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
268f0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
26900 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
26910 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
26920 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
26930 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
26940 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
26950 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
26960 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
26970 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
26980 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
26990 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
269a0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
269b0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
269c0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
269d0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
269e0 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
269f0 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
26a00 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
26a10 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
26a20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
26a30 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
26a40 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
26a50 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
26a60 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
26a70 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
26a80 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
26a90 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
26aa0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
26ab0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
26ac0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
26ad0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
26ae0 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
26af0 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
26b00 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
26b10 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
26b20 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
26b30 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
26b40 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
26b50 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
26b60 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
26b70 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
26b80 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
26b90 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
26ba0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
26bb0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
26bc0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
26bd0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
26be0 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
26bf0 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
26c00 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
26c10 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
26c20 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
26c30 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
26c40 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
26c50 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
26c60 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26c70 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
26c80 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
26c90 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
26ca0 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
26cb0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
26cc0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
26cd0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
26ce0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
26cf0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
26d00 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
26d10 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
26d20 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
26d30 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
26d40 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
26d50 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
26d60 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
26d70 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
26d80 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
26d90 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
26da0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
26db0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
26dc0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
26dd0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
26de0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
26df0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
26e00 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
26e10 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
26e20 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
26e30 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
26e40 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
26e50 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
26e60 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
26e70 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
26e80 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
26e90 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
26ea0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
26eb0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
26ec0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
26ed0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
26ee0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
26ef0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
26f00 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
26f10 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
26f20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
26f30 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
26f40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
26f50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26f60 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26f70 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
26f80 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
26f90 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
26fa0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
26fb0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
26fc0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
26fd0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
26fe0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
26ff0 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
27000 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
27010 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
27020 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
27030 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
27040 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27050 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
27060 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
27070 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
27080 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
27090 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
270a0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
270b0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
270c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
270d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
270e0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
270f0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
27100 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
27110 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
27120 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
27130 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
27140 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
27150 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
27160 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
27170 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
27180 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27190 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
271a0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
271b0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
271c0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
271d0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
271e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
271f0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
27200 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
27210 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
27220 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
27230 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
27240 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
27250 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
27260 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
27270 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
27280 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
27290 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
272a0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
272b0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
272c0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
272d0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
272e0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
272f0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
27300 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
27310 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
27320 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27330 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27340 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
27350 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
27360 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
27370 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
27380 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
27390 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
273a0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
273b0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
273c0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
273d0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
273e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
273f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
27400 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
27410 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
27420 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
27430 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
27440 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
27450 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
27460 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
27470 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
27480 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
27490 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
274a0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
274b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
274c0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
274d0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
274e0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
274f0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
27500 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
27510 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
27520 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
27530 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
27540 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
27550 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
27560 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
27570 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
27580 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
27590 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
275a0 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
275b0 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
275c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
275d0 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
275e0 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
275f0 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
27600 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
27610 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
27620 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
27630 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27640 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
27650 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
27660 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
27670 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
27680 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
27690 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
276a0 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
276b0 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
276c0 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
276d0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
276e0 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
276f0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
27700 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
27710 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
27720 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
27730 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
27740 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
27750 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
27760 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
27770 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
27780 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
27790 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
277a0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
277b0 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
277c0 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
277d0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
277e0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
277f0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
27800 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
27810 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
27820 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
27830 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
27840 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
27850 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27860 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
27870 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
27880 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
27890 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
278a0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
278b0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
278c0 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
278d0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
278e0 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
278f0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
27900 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
27910 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
27920 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
27930 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
27940 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
27950 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
27960 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
27970 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
27980 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
27990 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
279a0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
279b0 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
279c0 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
279d0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
279e0 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
279f0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
27a00 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
27a10 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
27a20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
27a30 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
27a40 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
27a50 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
27a60 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
27a70 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
27a80 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
27a90 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
27aa0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
27ab0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
27ac0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
27ad0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
27ae0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
27af0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
27b00 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
27b10 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
27b20 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
27b30 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
27b40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
27b50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
27b60 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
27b70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
27b80 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
27b90 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
27ba0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
27bb0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
27bc0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
27bd0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
27be0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
27bf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27c00 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
27c10 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27c20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
27c30 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
27c40 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
27c50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
27c60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27c70 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
27c80 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
27c90 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
27ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
27cb0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
27cc0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
27cd0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
27ce0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
27cf0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
27d00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27d10 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
27d20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
27d30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27d40 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
27d50 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
27d60 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
27d70 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
27d80 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
27d90 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
27da0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
27db0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
27dc0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
27dd0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
27de0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
27df0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
27e00 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
27e10 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
27e20 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
27e30 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
27e40 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
27e50 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
27e60 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
27e70 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
27e80 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
27e90 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
27ea0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
27eb0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
27ec0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
27ed0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
27ee0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
27ef0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27f00 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
27f10 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
27f20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27f30 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
27f40 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
27f50 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
27f60 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
27f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
27f80 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
27f90 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
27fa0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
27fb0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
27fc0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
27fd0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
27fe0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
27ff0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
28000 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
28010 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
28020 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
28030 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
28040 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
28050 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
28060 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
28070 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
28080 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
28090 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
280a0 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
280b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
280c0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
280d0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
280e0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
280f0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
28100 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
28110 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
28120 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
28130 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
28140 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
28150 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
28160 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
28170 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
28180 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
28190 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
281a0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
281b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
281c0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
281d0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
281e0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
281f0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
28200 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
28210 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
28220 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
28230 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
28240 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
28250 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
28260 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
28270 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28280 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
28290 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
282a0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
282b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
282c0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
282d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
282e0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
282f0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
28300 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
28310 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
28320 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
28330 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
28340 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28350 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28360 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
28370 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
28380 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
28390 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
283a0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
283b0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
283c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
283d0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
283e0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
283f0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
28400 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
28410 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
28420 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
28430 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
28440 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
28450 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
28460 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
28470 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
28480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
28490 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
284a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
284b0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
284c0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
284d0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
284e0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
284f0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
28500 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
28510 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
28520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
28530 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
28540 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
28550 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
28560 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
28570 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
28580 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28590 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
285a0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
285b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
285c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
285d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
285e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
285f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28600 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
28610 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
28620 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
28630 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
28640 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
28650 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
28660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
28670 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
28680 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
28690 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
286a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
286b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
286c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
286d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
286e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
286f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
28700 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
28710 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
28720 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
28730 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
28740 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
28750 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
28760 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
28770 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
28780 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
28790 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
287a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
287b0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
287c0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
287d0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
287e0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
287f0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
28800 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
28810 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
28820 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
28830 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
28840 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
28850 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
28860 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
28870 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
28880 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
28890 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
288a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
288b0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
288c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
288d0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
288e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
288f0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
28900 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
28910 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
28920 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
28930 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
28940 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
28950 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
28960 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
28970 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
28980 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
28990 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
289a0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
289b0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
289c0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
289d0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
289e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
289f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
28a00 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
28a10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
28a20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
28a30 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
28a40 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
28a50 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
28a60 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
28a70 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
28a80 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
28a90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
28aa0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
28ab0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
28ac0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
28ad0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
28ae0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28af0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
28b00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
28b10 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
28b20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
28b30 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
28b40 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
28b50 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
28b60 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
28b70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28b80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
28b90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
28ba0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
28bb0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
28bc0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
28bd0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
28be0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
28bf0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
28c00 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
28c10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
28c20 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
28c30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
28c40 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
28c50 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
28c60 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
28c70 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
28c80 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
28c90 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
28ca0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
28cb0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
28cc0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
28cd0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
28ce0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
28cf0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
28d00 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
28d10 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
28d20 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
28d30 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
28d40 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
28d50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
28d60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
28d70 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
28d80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
28d90 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
28da0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
28db0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
28dc0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
28dd0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
28de0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
28df0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
28e00 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
28e10 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
28e20 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
28e30 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
28e40 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
28e50 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
28e60 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
28e70 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
28e80 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
28e90 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
28ea0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
28eb0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
28ec0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28ed0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
28ee0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
28ef0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
28f00 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
28f10 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
28f20 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
28f30 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
28f40 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
28f50 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
28f60 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
28f70 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
28f80 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
28f90 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
28fa0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
28fb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28fc0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
28fd0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
28fe0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
28ff0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
29000 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
29010 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
29020 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
29030 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
29040 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
29050 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
29060 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
29070 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
29080 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
29090 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
290a0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
290b0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
290c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
290d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
290e0 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
290f0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
29100 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
29110 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29120 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
29130 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
29140 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
29150 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
29160 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
29170 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
29180 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
29190 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
291a0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 5e  * API call..** ^
291b0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
291c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
291d0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
291e0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
291f0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
29200 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
29210 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29220 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
29230 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29240 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
29250 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bled..**.** The 
29260 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
29270 62 79 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  by sqlite3_errco
29280 64 65 28 29 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  de() and/or.** s
29290 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
292a0 65 72 72 63 6f 64 65 28 29 20 6d 69 67 68 74 20  errcode() might 
292b0 63 68 61 6e 67 65 20 77 69 74 68 20 65 61 63 68  change with each
292c0 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 45 78   API call..** Ex
292d0 63 65 70 74 2c 20 74 68 65 72 65 20 61 72 65 20  cept, there are 
292e0 73 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  some interfaces 
292f0 74 68 61 74 20 61 72 65 20 67 75 61 72 61 6e 74  that are guarant
29300 65 65 64 20 74 6f 20 6e 65 76 65 72 0a 2a 2a 20  eed to never.** 
29310 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
29320 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 63 6f   of the error co
29330 64 65 2e 20 20 54 68 65 20 65 72 72 6f 72 2d 63  de.  The error-c
29340 6f 64 65 20 70 72 65 73 65 72 76 69 6e 67 0a 2a  ode preserving.*
29350 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
29360 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
29370 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
29380 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73  code().** <li> s
29390 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
293a0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c 6c 69  errcode().** <li
293b0 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  > sqlite3_errmsg
293c0 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
293d0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 0a 2a 2a  e3_errmsg16().**
293e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68   </ul>.**.** ^Th
293f0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
29400 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
29410 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
29420 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
29430 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
29440 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
29450 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
29460 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
29470 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
29480 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
29490 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
294a0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
294b0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
294c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
294d0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
294e0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
294f0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
29500 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
29510 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
29520 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
29530 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
29540 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
29550 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
29560 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
29570 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
29580 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
29590 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
295a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
295b0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
295c0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
295d0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
295e0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
295f0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
29600 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
29610 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
29620 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
29630 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
29640 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
29650 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
29660 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
29670 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
29680 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
29690 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
296a0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
296b0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
296c0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
296d0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
296e0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
296f0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
29700 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
29710 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
29720 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
29730 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
29740 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
29750 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
29760 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
29770 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
29780 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
29790 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
297a0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
297b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
297c0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
297d0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
297e0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
297f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29800 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
29810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
29820 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
29830 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
29840 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
29850 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
29860 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
29870 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
29880 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
29890 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
298a0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
298b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
298c0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
298d0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
298e0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
298f0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
29900 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
29910 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
29920 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
29930 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
29940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
29950 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
29960 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
29970 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
29980 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
29990 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
299a0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
299b0 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
299c0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
299d0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
299e0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
299f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
29a00 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
29a10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
29a20 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
29a30 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
29a40 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
29a50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29a60 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
29a70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
29a80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
29a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
29aa0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
29ab0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
29ac0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
29ad0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
29ae0 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
29af0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
29b00 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
29b10 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
29b20 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
29b30 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
29b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
29b50 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
29b60 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
29b70 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
29b80 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
29b90 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
29ba0 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
29bb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29bc0 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
29bd0 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
29be0 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
29bf0 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
29c00 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
29c10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29c20 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
29c30 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
29c40 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
29c50 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
29c60 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
29c70 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
29c80 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
29c90 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
29ca0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29cb0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
29cc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
29cd0 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
29ce0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
29cf0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
29d00 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
29d10 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
29d20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
29d30 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
29d40 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
29d50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29d60 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
29d70 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
29d80 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29d90 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
29da0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29db0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
29dc0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
29dd0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
29de0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
29df0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
29e00 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
29e10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29e20 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
29e30 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
29e40 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
29e50 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
29e60 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
29e70 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
29e80 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
29e90 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
29ea0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
29eb0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
29ec0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
29ed0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
29ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
29ef0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
29f00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
29f10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
29f20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29f30 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
29f40 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
29f50 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
29f60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
29f70 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
29f80 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
29f90 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
29fa0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
29fb0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
29fc0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
29fd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29fe0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
29ff0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
2a000 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
2a010 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
2a020 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
2a030 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
2a040 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
2a050 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
2a060 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
2a070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
2a080 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
2a090 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
2a0a0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2a0b0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
2a0c0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
2a0d0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
2a0e0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
2a0f0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
2a100 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
2a110 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
2a120 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
2a130 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
2a140 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
2a150 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
2a160 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
2a170 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
2a180 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
2a190 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
2a1a0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
2a1b0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
2a1c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2a1d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2a1e0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
2a1f0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
2a200 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
2a210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2a220 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
2a230 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
2a240 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
2a250 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
2a260 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
2a270 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
2a280 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
2a290 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
2a2a0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
2a2b0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
2a2c0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
2a2d0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
2a2e0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2a2f0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
2a300 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
2a310 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
2a320 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2a330 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
2a340 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
2a350 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
2a360 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
2a370 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
2a380 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
2a390 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
2a3a0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
2a3b0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
2a3c0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
2a3d0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
2a3e0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
2a3f0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
2a400 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
2a410 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
2a420 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
2a430 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
2a440 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2a450 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
2a460 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
2a470 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
2a480 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
2a490 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
2a4a0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
2a4b0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
2a4c0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
2a4d0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
2a4e0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
2a4f0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
2a500 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
2a510 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
2a520 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2a530 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
2a540 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
2a550 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
2a560 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
2a570 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
2a580 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
2a590 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
2a5a0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
2a5b0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
2a5c0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
2a5d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
2a5e0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
2a5f0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
2a600 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
2a610 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2a620 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
2a630 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
2a640 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
2a650 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
2a660 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
2a670 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
2a680 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
2a690 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
2a6a0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
2a6b0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
2a6c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
2a6d0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
2a6e0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
2a6f0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
2a700 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
2a710 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
2a720 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
2a730 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
2a740 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
2a750 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
2a760 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
2a770 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
2a780 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
2a790 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
2a7a0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
2a7b0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
2a7c0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
2a7d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
2a7e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a7f0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
2a800 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a810 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
2a820 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
2a830 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
2a840 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
2a850 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
2a860 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
2a870 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
2a880 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
2a890 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a8a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
2a8b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
2a8c0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
2a8d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a8e0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
2a8f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a900 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
2a910 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a920 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2a930 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
2a940 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
2a950 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
2a960 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
2a970 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
2a980 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2a990 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
2a9a0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
2a9b0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
2a9c0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
2a9d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
2a9e0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
2a9f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
2aa00 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
2aa10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2aa20 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
2aa30 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
2aa40 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
2aa50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2aa60 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2aa70 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
2aa80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
2aa90 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
2aaa0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2aab0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2aac0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
2aad0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
2aae0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
2aaf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2ab00 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
2ab10 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2ab20 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
2ab30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2ab40 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
2ab50 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
2ab60 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
2ab70 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
2ab80 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
2ab90 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73  tatement.  If [s
2aba0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2abb0 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65  2()] or.** the e
2abc0 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20  quivalent tries 
2abd0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63  to allocate spac
2abe0 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20  e for more than 
2abf0 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65  this many opcode
2ac00 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65  s.** in a single
2ac10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ac20 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e  ent, an SQLITE_N
2ac30 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65  OMEM error is re
2ac40 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
2ac50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ac60 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2ac70 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2ac80 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2ac90 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
2aca0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2acb0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
2acc0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
2acd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2ace0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2acf0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
2ad00 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2ad10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2ad20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2ad30 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
2ad40 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
2ad50 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
2ad60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
2ad70 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2ad80 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
2ad90 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
2ada0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
2adb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2adc0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2add0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
2ade0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
2adf0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
2ae00 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
2ae10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2ae20 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2ae30 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
2ae40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
2ae50 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
2ae60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2ae70 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
2ae80 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
2ae90 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
2aea0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
2aeb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2aec0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2aed0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2aee0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2aef0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2af00 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2af10 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
2af20 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
2af30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2af40 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2af50 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e  THREADS]] ^(<dt>
2af60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
2af70 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e  KER_THREADS</dt>
2af80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2af90 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75  mum number of au
2afa0 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74  xiliary worker t
2afb0 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69  hreads that a si
2afc0 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65  ngle.** [prepare
2afd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79  d statement] may
2afe0 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a   start.</dd>)^.*
2aff0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2b000 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2b010 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2b020 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
2b030 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2b040 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
2b050 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2b060 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2b070 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
2b080 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
2b090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2b0a0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
2b0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
2b0c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2b0d0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2b0e0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
2b0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b100 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
2b110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
2b120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b130 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2b140 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
2b150 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
2b160 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
2b170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b180 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
2b190 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2b1a0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
2b1b0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
2b1c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2b1d0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
2b1e0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
2b1f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
2b200 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2b210 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
2b220 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2b230 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20  R_THREADS       
2b240 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41      11../*.** CA
2b250 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20  PI3REF: Prepare 
2b260 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
2b270 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
2b280 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73  ne various flags
2b290 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73   that can be pas
2b2a0 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65  sed into.** "pre
2b2b0 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65  pFlags" paramete
2b2c0 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  r of the [sqlite
2b2d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
2b2e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2b2f0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2b300 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a  interfaces..**.*
2b310 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20  * New flags may 
2b320 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2b330 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2b340 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  QLite..**.** <dl
2b350 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52  >.** [[SQLITE_PR
2b360 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2b370 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2b380 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2b390 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  NT</dt>.** <dd>T
2b3a0 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  he SQLITE_PREPAR
2b3b0 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61  E_PERSISTENT fla
2b3c0 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74  g is a hint to t
2b3d0 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  he query planner
2b3e0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65  .** that the pre
2b3f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b400 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64  will be retained
2b410 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65   for a long time
2b420 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79   and.** probably
2b430 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d   reused many tim
2b440 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74  es.)^ ^Without t
2b450 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74  his flag, [sqlit
2b460 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2b470 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b480 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2b490 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65   assume that the
2b4a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b4b0 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20  ent will .** be 
2b4c0 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f  used just once o
2b4d0 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20  r at most a few 
2b4e0 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64  times and then d
2b4f0 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a  estroyed using.*
2b500 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2b510 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c  ize()] relativel
2b520 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72  y soon. The curr
2b530 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2b540 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68  on acts.** on th
2b550 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64  is hint by avoid
2b560 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b  ing the use of [
2b570 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2b580 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a  ] so as not to.*
2b590 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69  * deplete the li
2b5a0 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c  mited store of l
2b5b0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
2b5c0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
2b5d0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61   of.** SQLite ma
2b5e0 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69  y act on this hi
2b5f0 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a  nt differently..
2b600 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2b610 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2b620 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20  RE_PERSISTENT   
2b630 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a             0x01.
2b640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b650 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
2b660 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
2b670 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
2b680 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
2b690 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2b6a0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
2b6b0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
2b6c0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
2b6d0 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  te an SQL statem
2b6e0 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ent, it must fir
2b6f0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
2b700 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
2b710 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
2b720 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
2b730 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20  utines.  Or, in 
2b740 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2b750 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2b760 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20  re constructors 
2b770 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2b780 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
2b790 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ect..**.** The p
2b7a0 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65  referred routine
2b7b0 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69   to use is [sqli
2b7c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b7d0 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  ].  The.** [sqli
2b7e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69  te3_prepare()] i
2b7f0 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61  nterface is lega
2b800 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65  cy and should be
2b810 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71   avoided..** [sq
2b820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b830 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61  ()] has an extra
2b840 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74   "prepFlags" opt
2b850 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64  ion that is used
2b860 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20  .** for special 
2b870 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
2b880 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55  The use of the U
2b890 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20  TF-8 interfaces 
2b8a0 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73  is preferred, as
2b8b0 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c   SQLite currentl
2b8c0 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61  y.** does all pa
2b8d0 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d  rsing using UTF-
2b8e0 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69  8.  The UTF-16 i
2b8f0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
2b900 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63  ovided.** as a c
2b910 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65  onvenience.  The
2b920 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2b930 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65  es work by conve
2b940 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70  rting the.** inp
2b950 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46  ut text into UTF
2b960 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e  -8, then invokin
2b970 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  g the correspond
2b980 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66  ing UTF-8 interf
2b990 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ace..**.** The f
2b9a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
2b9b0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
2b9c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b9d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
2b9e0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
2b9f0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2ba00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2ba10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2ba20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2ba30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
2ba40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ba50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
2ba60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
2ba70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2ba80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
2ba90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
2baa0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2bab0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
2bac0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2bad0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
2bae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2baf0 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  , sqlite3_prepar
2bb00 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73  e_v2(),.** and s
2bb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bb20 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  3().** interface
2bb30 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
2bb40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bb50 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  16(), sqlite3_pr
2bb60 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2bb70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2bb80 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20  pare16_v3() use 
2bb90 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
2bba0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
2bbb0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
2bbc0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
2bbd0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
2bbe0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2bbf0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
2bc00 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
2bc10 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
2bc20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2bc30 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
2bc40 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
2bc50 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
2bc60 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2bc70 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
2bc80 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
2bc90 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
2bca0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
2bcb0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
2bcc0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
2bcd0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
2bce0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
2bcf0 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
2bd00 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
2bd10 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
2bd20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2bd30 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
2bd40 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
2bd50 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
2bd60 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2bd70 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
2bd80 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
2bd90 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
2bda0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
2bdb0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
2bdc0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
2bdd0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
2bde0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
2bdf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
2be00 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
2be10 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
2be20 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
2be30 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
2be40 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
2be50 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
2be60 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
2be70 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
2be80 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
2be90 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
2bea0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
2beb0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
2bec0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
2bed0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
2bee0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
2bef0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
2bf00 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
2bf10 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
2bf20 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
2bf30 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
2bf40 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
2bf50 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
2bf60 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
2bf70 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
2bf80 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
2bf90 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
2bfa0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
2bfb0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
2bfc0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2bfd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bfe0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
2bff0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
2c000 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
2c010 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
2c020 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
2c030 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
2c040 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
2c050 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
2c060 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2c070 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
2c080 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
2c090 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2c0a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2c0b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20  3_prepare_v2(), 
2c0c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c0d0 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v3(), sqlite3_pr
2c0e0 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a  epare16_v2(),.**
2c0f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2c100 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65  pare16_v3() inte
2c110 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d  rfaces are recom
2c120 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2c130 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20  ew programs..** 
2c140 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  The older interf
2c150 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72  aces (sqlite3_pr
2c160 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
2c170 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29  te3_prepare16())
2c180 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64  .** are retained
2c190 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2c1a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2c1b0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2c1c0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2c1d0 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  In the "vX" inte
2c1e0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2c1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2c200 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2c210 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2c220 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2c230 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2c240 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2c250 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2c260 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2c270 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2c280 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2c290 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2c2a0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2c2b0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2c2c0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2c2d0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2c2e0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2c2f0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2c300 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2c310 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2c320 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2c330 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2c340 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2c350 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2c360 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2c370 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2c380 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2c390 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2c3a0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2c3b0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2c3c0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2c3d0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2c3e0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2c3f0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2c400 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2c410 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2c420 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c430 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2c440 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2c450 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2c460 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2c470 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2c480 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2c490 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2c4a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c4b0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2c4c0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2c4d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2c4e0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2c4f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2c500 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2c510 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2c520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2c530 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2c540 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2c550 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2c560 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2c570 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2c580 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2c590 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2c5a0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2c5b0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2c5c0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2c5d0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2c5e0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2c5f0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2c600 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2c610 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2c620 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2c630 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2c640 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2c650 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2c660 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2c670 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2c680 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2c690 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2c6a0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2c6b0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2c6c0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2c6d0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2c6e0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2c6f0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2c700 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2c710 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2c720 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2c730 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2c740 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2c750 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2c760 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2c770 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2c780 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2c790 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2c7a0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2c7b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2c7c0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2c7d0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2c7e0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2c7f0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2c800 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2c810 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2c820 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2c830 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2c840 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2c850 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2c860 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2c870 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2c880 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74  .**.** <p>^sqlit
2c890 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2c8a0 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c  differs from sql
2c8b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c8c0 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67  ) only in having
2c8d0 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70 72  .** the extra pr
2c8e0 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65  epFlags paramete
2c8f0 72 2c 20 77 68 69 63 68 20 69 73 20 61 20 62 69  r, which is a bi
2c900 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69  t array consisti
2c910 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a  ng of zero or.**
2c920 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
2c930 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2c940 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50  SISTENT|SQLITE_P
2c950 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e  REPARE_*] flags.
2c960 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2c970 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 69  3_prepare_v2() i
2c980 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65  nterface works e
2c990 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
2c9a0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  as.** sqlite3_pr
2c9b0 65 70 61 72 65 5f 76 33 28 29 20 77 69 74 68 20  epare_v3() with 
2c9c0 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73  a zero prepFlags
2c9d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69   parameter..*/.i
2c9e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2c9f0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2ca00 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2ca10 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2ca20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ca30 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2ca40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ca50 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2ca60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ca70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ca80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ca90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2caa0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2cab0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cac0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cad0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cae0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2caf0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cb00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cb10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cb20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cb30 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2cb40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2cb50 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2cb60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2cb70 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2cb80 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2cb90 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2cba0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2cbb0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2cbc0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cbd0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2cbe0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2cbf0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2cc00 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2cc10 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2cc20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2cc30 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2cc40 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2cc50 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2cc60 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2cc70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a  te3_prepare_v3(.
2cc80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2cc90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2cca0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2ccb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2ccc0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2ccd0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2cce0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2ccf0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2cd00 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2cd10 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2cd20 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2cd30 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2cd40 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2cd50 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2cd60 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2cd70 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cd80 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cd90 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cda0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2cdb0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2cdc0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cdd0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cde0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cdf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2ce00 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2ce10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ce20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2ce30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ce40 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2ce50 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ce60 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2ce70 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2ce80 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2ce90 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2cea0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2ceb0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2cec0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2ced0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2cee0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2cef0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2cf00 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2cf10 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2cf20 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2cf30 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2cf40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cf50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2cf60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2cf70 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2cf80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2cf90 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2cfa0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2cfb0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2cfc0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2cfd0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2cfe0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2cff0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2d000 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2d010 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2d020 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2d030 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2d040 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2d050 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2d060 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2d070 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2d080 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2d090 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69  are16_v3(.  sqli
2d0a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2d0b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2d0c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2d0d0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2d0e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2d0f0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2d100 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2d110 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2d120 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2d130 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2d140 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2d150 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2d160 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2d170 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2d180 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2d190 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2d1a0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2d1b0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2d1c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d1d0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2d1e0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2d1f0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2d200 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
2d210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
2d220 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
2d230 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
2d240 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2d250 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d260 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2d270 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2d280 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66  ter to a copy of
2d290 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51   the UTF-8.** SQ
2d2a0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
2d2b0 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20  reate [prepared 
2d2c0 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20  statement] P if 
2d2d0 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64  P was.** created
2d2e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2d2f0 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2d300 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2d310 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2d320 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
2d330 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d340 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
2d350 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2d360 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2d370 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d380 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2d390 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2d3a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2d3b0 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2d3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2d3d0 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2d3e0 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2d3f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2d400 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2d410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d420 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2d430 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2d440 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2d450 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2d460 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2d470 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2d480 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2d490 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2d4a0 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2d4b0 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2d4c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2d4d0 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2d4e0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2d4f0 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2d500 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2d510 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2d520 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2d530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d540 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d550 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d560 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2d570 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2d580 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2d590 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2d5a0 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2d5b0 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2d5c0 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2d5d0 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2d5e0 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2d5f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2d600 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2d610 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2d620 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2d630 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2d640 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2d650 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2d660 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2d670 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2d680 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2d690 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2d6a0 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2d6b0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d6c0 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2d6d0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2d6e0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2d6f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d700 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2d710 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2d720 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2d730 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2d740 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2d750 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2d760 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2d770 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2d780 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2d790 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2d7a0 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2d7b0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2d7c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2d7d0 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2d7e0 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2d7f0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2d800 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2d810 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2d820 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2d830 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2d840 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d850 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2d860 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2d870 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d890 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2d8a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2d8b0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2d8c0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2d8d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d8e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2d8f0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2d900 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d910 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2d920 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2d930 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2d940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2d950 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2d960 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2d970 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2d980 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2d990 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2d9a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d9b0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d9c0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2d9d0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2d9e0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2d9f0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2da00 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2da10 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2da20 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2da30 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2da40 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2da50 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2da60 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2da70 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2da80 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2da90 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2daa0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2dab0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2dac0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2dad0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2dae0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2daf0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2db00 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2db10 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2db20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2db30 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2db40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2db50 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2db60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2db70 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2db80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2db90 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2dba0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2dbb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2dbc0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2dbd0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2dbe0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2dbf0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2dc00 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2dc10 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2dc20 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2dc30 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2dc40 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2dc50 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2dc60 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2dc70 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2dc80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2dc90 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2dca0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2dcb0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2dcc0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2dcd0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2dce0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2dcf0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2dd00 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2dd10 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2dd20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2dd30 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2dd40 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2dd50 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2dd60 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2dd70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2dd80 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2dd90 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2dda0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2ddb0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2ddc0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2ddd0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2dde0 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2ddf0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2de00 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2de10 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2de20 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2de30 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2de40 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2de50 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2de60 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2de70 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2de80 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2de90 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2dea0 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2deb0 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2dec0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2ded0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2dee0 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2def0 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
2df00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2df10 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2df20 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2df30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2df40 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2df50 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2df60 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2df70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2df80 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2df90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2dfa0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2dfb0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2dfc0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2dfd0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2dfe0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2dff0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2e000 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2e010 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2e020 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
2e030 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
2e040 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
2e050 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2e060 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
2e070 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
2e080 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
2e090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e0a0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
2e0b0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
2e0c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2e0d0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
2e0e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e0f0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
2e100 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
2e110 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
2e120 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
2e130 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
2e140 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2e150 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
2e160 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2e170 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
2e180 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2e190 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2e1a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
2e1b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
2e1c0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
2e1d0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
2e1e0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
2e1f0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
2e200 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
2e210 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
2e220 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
2e230 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
2e240 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
2e250 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
2e260 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
2e270 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
2e280 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
2e290 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
2e2a0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
2e2b0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
2e2c0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
2e2d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2e2e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2e2f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e300 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2e310 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2e320 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2e330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e340 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2e350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e360 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2e370 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2e380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2e390 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2e3a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2e3b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2e3c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2e3d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2e3e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2e3f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2e400 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2e410 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2e420 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e430 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2e440 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2e450 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2e460 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2e470 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2e480 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e490 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2e4a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2e4b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2e4c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2e4d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2e4e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e4f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2e500 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2e510 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2e520 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2e530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e540 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2e550 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2e560 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2e570 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2e580 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2e590 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2e5a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2e5b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e5c0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2e5d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2e5e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2e5f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2e600 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2e610 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2e620 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2e630 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2e640 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2e650 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2e660 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2e670 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2e680 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2e690 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2e6a0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2e6b0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2e6c0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2e6d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2e6e0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2e6f0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2e700 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2e710 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2e720 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2e730 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2e740 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2e750 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2e760 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2e770 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2e780 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2e790 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2e7a0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2e7b0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2e7c0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2e7d0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2e7e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2e7f0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2e800 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2e810 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2e820 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2e830 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2e840 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2e850 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e860 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e870 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2e880 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2e890 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2e8a0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2e8b0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2e8c0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2e8d0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2e8e0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2e8f0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2e900 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2e910 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2e920 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e930 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2e940 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2e950 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2e960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e970 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e980 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2e990 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2e9a0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2e9b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2e9c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e9d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2e9e0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2e9f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ea00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2ea10 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2ea20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2ea30 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2ea40 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2ea50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ea60 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2ea70 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 61  nly be used as a
2ea80 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b  rguments.** to [
2ea90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2eaa0 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  alue()], [sqlite
2eab0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c  3_bind_value()],
2eac0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2ead0 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a  _value_dup()]..*
2eae0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2eaf0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2eb00 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2eb10 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2eb20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2eb30 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2eb40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2eb50 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2eb60 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  ruct sqlite3_val
2eb70 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ue sqlite3_value
2eb80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eb90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
2eba0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
2ebb0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
2ebc0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
2ebd0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
2ebe0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
2ebf0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
2ec00 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
2ec10 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
2ec20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2ec30 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
2ec40 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
2ec50 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
2ec60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ec70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
2ec80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ec90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2eca0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2ecb0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
2ecc0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
2ecd0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
2ece0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2ecf0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
2ed00 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
2ed10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2ed20 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
2ed30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2ed40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ed50 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2ed60 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
2ed70 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
2ed80 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
2ed90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2eda0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
2edb0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
2edc0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
2edd0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
2ede0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
2edf0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
2ee00 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
2ee10 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
2ee20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
2ee30 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
2ee40 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2ee50 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
2ee60 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
2ee70 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
2ee80 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
2ee90 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
2eea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2eeb0 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2eec0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2eed0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2eee0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2eef0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2ef00 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2ef10 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2ef20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2ef30 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2ef40 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2ef50 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2ef60 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2ef70 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2ef80 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2ef90 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2efa0 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2efb0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2efc0 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2efd0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2efe0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2eff0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2f000 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2f010 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2f020 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2f030 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2f040 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2f050 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2f060 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2f070 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2f080 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2f090 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2f0a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2f0b0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2f0c0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2f0d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2f0e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2f0f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2f100 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2f110 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2f120 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2f130 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2f140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2f150 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2f160 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2f170 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2f180 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2f190 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2f1a0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2f1b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2f1c0 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2f1d0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2f1e0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2f1f0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2f200 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2f210 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2f220 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2f230 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2f240 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2f250 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2f260 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2f270 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2f280 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2f290 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2f2a0 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2f2b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2f2c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2f2d0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2f2e0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2f2f0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2f300 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2f310 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2f320 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2f330 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2f340 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2f350 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2f360 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2f370 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2f380 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2f390 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2f3a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2f3b0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2f3c0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2f3d0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2f3e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2f3f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2f400 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f410 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f420 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2f430 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f440 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2f450 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2f460 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2f470 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2f480 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2f490 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2f4a0 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2f4b0 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2f4c0 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2f4d0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2f4e0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2f4f0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2f500 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2f510 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2f520 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2f530 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2f540 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2f550 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2f560 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2f570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2f580 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2f590 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2f5a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f5b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2f5c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f5d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2f5e0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2f5f0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2f600 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2f610 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f620 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2f630 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2f640 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2f650 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f670 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2f680 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2f690 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2f6a0 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2f6b0 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2f6c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2f6d0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2f6e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2f6f0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f700 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
2f710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2f720 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
2f730 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2f740 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2f750 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2f760 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2f770 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2f780 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2f790 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2f7a0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2f7b0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2f7c0 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2f7d0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2f7e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2f7f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f800 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2f810 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2f820 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2f830 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2f840 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2f850 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2f860 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2f870 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2f880 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2f890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2f8a0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
2f8b0 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
2f8c0 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
2f8d0 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
2f8e0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2f8f0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2f900 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2f910 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2f920 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2f930 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2f940 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2f950 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2f960 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2f970 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2f980 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49  call to bind API
2f990 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74   fails..** ^If t
2f9a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f9b0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2f9c0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2f9d0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2f9e0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2f9f0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2fa00 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2fa10 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2fa20 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2fa30 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2fa40 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2fa50 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2fa60 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2fa70 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2fa80 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2fa90 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2faa0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2fab0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2fac0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2fad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2fae0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2faf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
2fb00 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2fb10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2fb20 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
2fb30 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
2fb40 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2fb50 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
2fb60 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2fb70 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
2fb80 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
2fb90 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
2fba0 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
2fbb0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
2fbc0 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
2fbd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2fbe0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
2fbf0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
2fc00 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
2fc10 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
2fc20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
2fc30 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2fc40 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
2fc50 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
2fc60 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
2fc70 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2fc80 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2fc90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2fca0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fcb0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2fcc0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2fcd0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2fce0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2fcf0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2fd00 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2fd10 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2fd20 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2fd30 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2fd40 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2fd50 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2fd60 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2fd70 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2fd80 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2fd90 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2fda0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2fdb0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2fdc0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2fdd0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2fde0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2fdf0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2fe00 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2fe10 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2fe20 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2fe30 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2fe40 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2fe50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2fe60 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
2fe70 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75  r(S,I,P,T,D) rou
2fe80 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20  tine causes the 
2fe90 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  I-th parameter i
2fea0 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  n.** [prepared s
2feb0 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68  tatement] S to h
2fec0 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65  ave an SQL value
2fed0 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f   of NULL, but to
2fee0 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f   also be.** asso
2fef0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2ff00 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70  pointer P of typ
2ff10 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68  e T.  ^D is eith
2ff20 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
2ff30 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  r or.** a pointe
2ff40 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f  r to a destructo
2ff50 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50  r function for P
2ff60 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  . ^SQLite will i
2ff70 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73  nvoke the.** des
2ff80 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
2ff90 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2ffa0 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73   of P when it is
2ffb0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a   finished using.
2ffc0 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72  ** P.  The T par
2ffd0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
2ffe0 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67   a static string
2fff0 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73  , preferably a s
30000 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c  tring.** literal
30010 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  . The sqlite3_bi
30020 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75  nd_pointer() rou
30030 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20  tine is part of 
30040 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20  the.** [pointer 
30050 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63  passing interfac
30060 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c  e] added for SQL
30070 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a  ite 3.20.0..**.*
30080 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
30090 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
300a0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
300b0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
300c0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
300d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
300e0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
300f0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
30100 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
30110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
30120 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
30130 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
30140 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
30150 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
30160 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
30170 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
30180 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
30190 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
301a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
301b0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
301c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
301d0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
301e0 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
301f0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
30200 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
30210 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
30220 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
30230 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
30240 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30250 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
30260 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
30270 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
30280 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
30290 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
302a0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
302b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
302c0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
302d0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
302e0 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
302f0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
30300 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
30310 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
30320 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
30330 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
30340 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
30350 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
30360 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
30370 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
30380 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
30390 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
303a0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
303b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
303c0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
303d0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
303e0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
303f0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
30400 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
30410 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
30420 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30430 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
30440 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
30450 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30460 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
30470 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30480 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30490 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
304a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
304b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
304c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
304d0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
304e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
304f0 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
30500 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30510 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
30520 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
30530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30540 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
30550 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
30560 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
30570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30580 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
30590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
305a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
305b0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
305c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
305d0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
305e0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
305f0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
30600 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
30610 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
30620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30630 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
30640 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
30650 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
30660 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
30670 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
30680 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30690 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
306a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
306b0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
306c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
306d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
306e0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
306f0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
30700 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30710 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
30720 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
30730 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
30740 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
30750 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
30760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
30770 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
30780 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
30790 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73  3_bind_pointer(s
307a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
307b0 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  t, void*, const 
307c0 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f  char*,void(*)(vo
307d0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
307e0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
307f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30800 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  int, int n);.int
30810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
30820 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
30830 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
30840 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f  ite3_uint64);../
30850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30860 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
30870 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f  ameters.** METHO
30880 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30890 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
308a0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
308b0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
308c0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
308d0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
308e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
308f0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
30900 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
30910 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
30920 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
30930 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
30940 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
30950 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
30960 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
30970 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
30980 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
30990 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
309a0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
309b0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
309c0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
309d0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
309e0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
309f0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
30a00 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
30a10 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
30a20 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
30a30 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
30a40 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
30a50 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
30a60 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
30a70 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
30a80 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
30a90 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
30aa0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
30ab0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
30ac0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30ad0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30ae0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
30af0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30b00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
30b10 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
30b20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
30b30 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
30b40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30b50 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
30b60 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
30b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
30b80 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
30b90 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44  ameter.** METHOD
30ba0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30bb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30bc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30bd0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
30be0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
30bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30c00 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
30c10 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
30c20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30c30 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
30c40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
30c50 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
30c60 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
30c70 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
30c80 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
30c90 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
30ca0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
30cb0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
30cc0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
30cd0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
30ce0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
30cf0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
30d00 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
30d10 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
30d20 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
30d30 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
30d40 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
30d50 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
30d60 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
30d70 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
30d80 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
30d90 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
30da0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
30db0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
30dc0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
30dd0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
30de0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
30df0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30e00 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
30e10 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
30e20 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
30e30 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
30e40 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
30e50 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
30e60 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
30e70 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
30e80 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
30e90 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
30ea0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
30eb0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
30ec0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
30ed0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
30ee0 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  re16()],.** [sql
30ef0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30f00 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
30f10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
30f20 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
30f30 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30f40 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30f50 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30f60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30f70 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
30f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30f90 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
30fa0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
30fb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
30fc0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30fd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30fe0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
30ff0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
31000 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
31010 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
31020 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31030 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
31040 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
31050 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
31060 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
31070 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
31080 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
31090 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
310a0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
310b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
310c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
310d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
310e0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
310f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
31100 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
31110 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
31120 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
31130 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
31140 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
31150 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
31160 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
31170 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
31180 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
31190 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
311a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
311b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
311c0 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
311d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
311e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
311f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
31200 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
31210 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
31220 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
31230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31240 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
31250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
31260 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
31270 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
31280 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
31290 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
312a0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
312b0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
312c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
312d0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
312e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
312f0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
31300 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
31310 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
31320 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
31330 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
31340 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
31350 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
31360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31370 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
31380 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
31390 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
313a0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
313b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
313c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
313d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
313e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
313f0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
31400 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31410 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31430 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
31440 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31450 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31460 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
31470 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31480 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69  tement]. ^If thi
31490 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
314a0 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  s 0, that means 
314b0 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
314c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74  d statement] ret
314d0 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f  urns no data (fo
314e0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
314f0 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65  DATE])..** ^Howe
31500 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73  ver, just becaus
31510 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  e this routine r
31520 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76  eturns a positiv
31530 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f  e number does no
31540 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f  t.** mean that o
31550 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ne or more rows 
31560 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20  of data will be 
31570 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45  returned.  ^A SE
31580 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a  LECT statement.*
31590 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61  * will always ha
315a0 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71  ve a positive sq
315b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
315c0 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69  nt() but dependi
315d0 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45  ng on the.** WHE
315e0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
315f0 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61  aints and the ta
31600 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20  ble content, it 
31610 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20  might return no 
31620 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  rows..**.** See 
31630 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
31640 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
31650 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
31660 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
31670 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31690 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
316a0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
316b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
316c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
316d0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
316e0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
316f0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
31700 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
31710 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31720 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
31730 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
31740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31750 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
31760 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
31770 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
31780 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
31790 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
317a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
317b0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
317c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
317d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
317e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
317f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31800 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
31810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
31820 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
31830 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
31840 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
31850 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
31860 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
31870 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
31880 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
31890 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
318a0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
318b0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
318c0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
318d0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
318e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
318f0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
31900 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
31910 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
31920 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31930 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
31940 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
31950 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
31960 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31970 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
31980 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
31990 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
319a0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
319b0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
319c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
319d0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
319e0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
319f0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
31a00 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
31a10 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
31a20 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
31a30 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
31a40 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
31a50 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
31a60 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
31a70 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
31a80 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
31a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
31aa0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
31ab0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
31ac0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
31ad0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
31ae0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
31af0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
31b00 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
31b10 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
31b20 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
31b30 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
31b40 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
31b50 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
31b60 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
31b70 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
31b80 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
31b90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
31ba0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
31bb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
31bc0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31be0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31bf0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
31c00 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
31c10 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
31c20 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
31c30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31c40 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31c50 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
31c60 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
31c70 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
31c80 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
31c90 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
31ca0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
31cb0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
31cc0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
31cd0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
31ce0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
31cf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
31d00 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
31d10 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
31d20 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
31d30 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
31d40 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
31d50 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
31d60 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
31d70 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
31d80 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
31d90 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
31da0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
31db0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
31dc0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
31dd0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
31de0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
31df0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
31e00 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
31e10 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31e20 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
31e30 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
31e40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31e50 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
31e60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
31e70 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
31e80 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
31e90 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
31ea0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31eb0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
31ec0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
31ed0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
31ee0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
31ef0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
31f00 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
31f10 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
31f20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
31f30 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
31f40 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
31f50 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
31f60 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
31f70 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
31f80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31f90 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
31fa0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
31fb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
31fc0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
31fd0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
31fe0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
31ff0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
32000 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
32010 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
32020 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
32030 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
32040 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
32050 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
32060 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
32070 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
32080 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
32090 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
320a0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
320b0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
320c0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
320d0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
320e0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
320f0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
32100 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
32110 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
32120 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
32130 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
32140 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
32150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
32160 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
32170 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
32180 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
32190 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
321a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
321b0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
321c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
321d0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
321e0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
321f0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
32200 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
32210 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
32220 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
32230 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
32240 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
32250 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
32260 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
32270 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
32280 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
32290 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
322a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
322b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
322c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
322d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
322e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
322f0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
32300 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
32310 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
32320 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
32330 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
32340 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
32350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32360 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
32370 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
32380 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32390 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
323a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
323b0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
323c0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
323d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
323e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
323f0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
32400 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
32410 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
32420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32430 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
32440 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
32450 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
32460 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
32470 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
32480 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32490 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
324a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
324b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
324c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
324d0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
324e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
324f0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
32500 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
32510 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
32520 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32530 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
32540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
32550 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
32560 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32570 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32580 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
32590 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
325a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
325b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
325c0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
325d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
325e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
325f0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
32600 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
32610 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
32620 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
32630 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
32640 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
32650 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
32660 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
32670 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
32680 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
32690 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
326a0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
326b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
326c0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
326d0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
326e0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
326f0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
32700 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
32710 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
32720 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
32730 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
32740 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
32750 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
32760 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
32770 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
32780 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
32790 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
327a0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
327b0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
327c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
327d0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
327e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
327f0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
32800 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
32810 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
32820 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
32830 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
32840 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
32850 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
32860 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
32870 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
32880 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
32890 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
328a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
328b0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
328c0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
328d0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
328e0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
328f0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
32900 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
32910 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
32920 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
32930 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
32940 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
32950 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
32960 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
32970 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
32980 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
32990 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
329a0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
329b0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
329c0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
329d0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
329e0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
329f0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
32a00 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
32a10 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
32a20 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
32a30 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
32a40 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
32a50 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
32a60 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
32a70 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
32a80 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
32a90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32aa0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
32ab0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
32ac0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
32ad0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32ae0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
32af0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32b10 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
32b20 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
32b30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
32b40 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
32b50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b60 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
32b70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e  repared using an
32b80 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y of.** [sqlite3
32b90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
32ba0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32bb0 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v3()], [sqlite3
32bc0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
32bd0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
32be0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
32bf0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
32c00 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
32c10 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
32c20 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
32c30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
32c40 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
32c50 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
32c60 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
32c70 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
32c80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
32c90 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
32ca0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
32cb0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
32cc0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
32cd0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
32ce0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
32cf0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
32d00 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
32d10 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
32d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
32d30 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
32d40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32d50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
32d60 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a  pare16_v3()],.**
32d70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32d80 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
32d90 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
32da0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
32db0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
32dc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
32dd0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
32de0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
32df0 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  w "vX" interface
32e00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
32e10 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
32e20 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
32e30 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32e40 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
32e50 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
32e60 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
32e70 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
32e80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32e90 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
32ea0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
32eb0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
32ec0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
32ed0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
32ee0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
32ef0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
32f00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
32f10 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
32f20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
32f30 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
32f40 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
32f50 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
32f60 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
32f70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
32f80 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
32f90 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
32fa0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
32fb0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
32fc0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
32fd0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
32fe0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
32ff0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
33000 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
33010 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
33020 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
33030 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
33040 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
33050 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
33060 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
33070 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
33080 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
33090 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
330a0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
330b0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
330c0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
330d0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
330e0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
330f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
33100 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
33110 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
33120 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
33130 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
33140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
33150 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
33160 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
33170 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
33180 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
33190 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
331a0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
331b0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
331c0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
331d0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
331e0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
331f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
33200 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
33210 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
33220 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
33230 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
33240 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
33250 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
33260 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
33270 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
33280 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
33290 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
332a0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
332b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
332c0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
332d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
332e0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
332f0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
33300 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
33310 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
33320 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
33330 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
33340 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
33350 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
33360 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
33370 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
33380 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
33390 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
333a0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
333b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
333c0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
333d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
333e0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
333f0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
33400 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
33410 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
33420 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
33430 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
33440 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
33450 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
33460 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
33470 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
33480 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
33490 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
334a0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
334b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
334c0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
334d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
334e0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
334f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
33500 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
33510 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
33520 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
33530 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
33540 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
33550 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
33560 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
33570 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
33580 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
33590 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
335a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
335b0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
335c0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
335d0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
335e0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
335f0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
33600 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
33610 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
33620 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
33630 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
33640 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
33650 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
33660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
33670 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
33680 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
33690 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
336a0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
336b0 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
336c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
336d0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
336e0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
336f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
33700 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
33710 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
33720 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
33730 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
33740 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
33750 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
33760 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
33770 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
33780 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
33790 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
337a0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
337b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
337c0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
337d0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
337e0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
337f0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
33800 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
33810 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
33820 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
33830 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
33840 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
33850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
33860 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
33870 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33880 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
33890 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
338a0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
338b0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
338c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
338d0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
338e0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
338f0 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
33900 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
33910 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
33920 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
33930 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
33940 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
33950 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
33960 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
33970 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
33980 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
33990 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
339a0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
339b0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
339c0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
339d0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
339e0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
339f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
33a00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
33a10 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
33a20 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
33a30 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
33a40 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
33a50 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
33a60 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
33a70 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
33a80 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
33a90 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
33aa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33ac0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
33ad0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
33ae0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
33af0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
33b00 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
33b10 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
33b20 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
33b30 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
33b40 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
33b50 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
33b60 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
33b70 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
33b80 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
33b90 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
33ba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
33bb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33bc0 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72  prepare_v3()] or
33bd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33be0 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  e_v2()].** or [s
33bf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33c00 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
33c10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
33c20 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
33c30 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
33c40 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
33c50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
33c60 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
33c70 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
33c80 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
33c90 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
33ca0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
33cb0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
33cc0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
33cd0 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69  se of the "vX" i
33ce0 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63  nterfaces is rec
33cf0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
33d00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
33d10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
33d20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
33d30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33d40 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
33d50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
33d60 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
33d70 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33d80 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
33d90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
33da0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
33db0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
33dc0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
33dd0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
33de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33df0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
33e00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
33e10 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
33e20 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
33e30 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
33e40 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
33e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
33e60 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
33e70 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
33e80 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
33e90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33ea0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
33eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
33ec0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
33ed0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
33ee0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
33ef0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
33f00 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33f10 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
33f20 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
33f30 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
33f40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
33f50 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
33f60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
33f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
33f80 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
33f90 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
33fa0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
33fb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33fc0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
33fd0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
33fe0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
33ff0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
34000 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
34010 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
34020 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
34030 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
34040 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
34050 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
34060 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
34070 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
34080 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34090 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
340a0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
340b0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
340c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
340d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
340e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
340f0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
34100 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
34110 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
34120 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
34130 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
34140 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
34150 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
34160 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
34170 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
34180 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
34190 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
341a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
341b0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
341c0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
341d0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
341e0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
341f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
34200 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
34210 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
34220 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
34230 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
34240 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
34250 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
34260 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
34270 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
34280 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
34290 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
342a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
342b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
342c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
342d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
342e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
342f0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
34300 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
34310 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
34320 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
34330 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
34340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34350 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
34360 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
34370 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
34380 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
34390 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
343a0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
343b0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
343c0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
343d0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
343e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
343f0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
34400 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
34410 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
34420 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
34430 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
34440 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
34450 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a  <b>Summary:</b>.
34460 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
34470 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63  table border=0 c
34480 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c  ellpadding=0 cel
34490 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c  lspacing=0>.** <
344a0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
344b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62  3_column_blob</b
344c0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42  ><td>&rarr;<td>B
344d0 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  LOB result.** <t
344e0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
344f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f  _column_double</
34500 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34510 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  REAL result.** <
34520 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34530 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e  3_column_int</b>
34540 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32  <td>&rarr;<td>32
34550 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
34560 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
34570 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
34580 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72  _int64</b><td>&r
34590 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49  arr;<td>64-bit I
345a0 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a  NTEGER result.**
345b0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
345c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c  te3_column_text<
345d0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
345e0 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75  >UTF-8 TEXT resu
345f0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34600 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34610 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72  text16</b><td>&r
34620 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54  arr;<td>UTF-16 T
34630 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EXT result.** <t
34640 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34650 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62  _column_value</b
34660 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54  ><td>&rarr;<td>T
34670 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20  he result as an 
34680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34690 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73  ue|unprotected s
346a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
346b0 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ject..** <tr><td
346c0 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
346d0 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c  ;<td>&nbsp;.** <
346e0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
346f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f  3_column_bytes</
34700 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34710 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a  Size of a BLOB.*
34720 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58  * or a UTF-8 TEX
34730 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65  T result in byte
34740 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  s.** <tr><td><b>
34750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34760 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73  ytes16&nbsp;&nbs
34770 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72  p;</b>.** <td>&r
34780 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  arr;&nbsp;&nbsp;
34790 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d  <td>Size of UTF-
347a0 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79  16.** TEXT in by
347b0 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  tes.** <tr><td><
347c0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
347d0 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  _type</b><td>&ra
347e0 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a  rr;<td>Default.*
347f0 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  * datatype of th
34800 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61  e result.** </ta
34810 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  ble></blockquote
34820 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69  >.**.** <b>Detai
34830 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54  ls:</b>.**.** ^T
34840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
34850 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
34860 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
34870 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
34880 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
34890 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
348a0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
348b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
348c0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
348d0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
348e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
348f0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
34900 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
34910 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
34920 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
34930 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
34940 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
34950 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
34960 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
34970 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
34980 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
34990 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
349a0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
349b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
349c0 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
349d0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
349e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
349f0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
34a00 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
34a10 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
34a20 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
34a30 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
34a40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34a50 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
34a60 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
34a70 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
34a80 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
34a90 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
34aa0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
34ab0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
34ac0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
34ad0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
34ae0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
34af0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
34b00 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
34b10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34b20 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
34b30 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
34b40 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
34b50 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
34b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
34b70 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
34b80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
34b90 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
34ba0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
34bb0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
34bc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
34bd0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
34be0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
34bf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
34c00 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
34c10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34c20 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
34c30 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
34c40 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
34c50 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
34c60 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
34c70 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
34c80 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
34c90 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
34ca0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34cb0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
34cc0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
34cd0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
34ce0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34cf0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
34d00 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
34d10 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34d20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
34d30 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66  first six interf
34d40 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f  aces (_blob, _do
34d50 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74  uble, _int, _int
34d60 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f  64, _text, and _
34d70 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20  text16).** each 
34d80 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65  return the value
34d90 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
34da0 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69  umn in a specifi
34db0 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20  c data format.  
34dc0 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  If.** the result
34dd0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69   column is not i
34de0 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20  nitially in the 
34df0 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74  requested format
34e00 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
34e10 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72  * if the query r
34e20 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
34e30 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65  r but the sqlite
34e40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
34e50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
34e60 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20  used to extract 
34e70 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20  the value) then 
34e80 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70  an automatic typ
34e90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
34ea0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a  performed..**.**
34eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
34ec0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
34ed0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
34ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
34ef0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
34f00 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
34f10 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
34f20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
34f30 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
34f40 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
34f50 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
34f60 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
34f70 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
34f80 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
34f90 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
34fa0 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68  ITE_NULL]..** Th
34fb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34fc0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
34fd0 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75  _type() can be u
34fe0 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68  sed to decide wh
34ff0 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69  ich.** of the fi
35000 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63  rst six interfac
35010 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64  e should be used
35020 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20   to extract the 
35030 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a  column value..**
35040 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
35050 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
35060 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
35070 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
35080 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74  if no.** automat
35090 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
350a0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
350b0 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20  d for the value 
350c0 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a  in question.  .*
350d0 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63  * After a type c
350e0 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72  onversion, the r
350f0 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67  esult of calling
35100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35110 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  type().** is und
35120 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68  efined, though h
35130 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65  armless.  Future
35140 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
35150 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
35160 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
35170 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
35180 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
35190 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
351a0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
351b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
351c0 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20   BLOB or a TEXT 
351d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  string, then the
351e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
351f0 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71  bytes().** or sq
35200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35210 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  es16() interface
35220 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
35230 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
35240 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42  ize.** of that B
35250 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
35260 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
35270 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
35280 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
35290 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
352a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
352b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
352c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
352d0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
352e0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
352f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35300 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
35310 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
35320 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
35330 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
35340 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
35350 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
35360 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
35370 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
35380 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
35390 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
353a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
353b0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
353c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
353d0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
353e0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
353f0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
35400 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
35410 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
35420 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
35430 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
35440 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
35450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35460 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
35470 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
35480 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
35490 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
354a0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
354b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
354c0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
354d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
354e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
354f0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
35500 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
35510 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
35520 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
35530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35540 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
35550 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
35560 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
35570 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
35580 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
35590 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
355a0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
355b0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
355c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
355d0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
355e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
355f0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
35600 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
35610 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
35620 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
35630 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35640 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
35650 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
35660 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
35670 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35680 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
35690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
356a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
356b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
356c0 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
356d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
356e0 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
356f0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
35700 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
35710 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
35720 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
35730 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
35740 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
35750 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
35760 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
35770 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
35780 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
35790 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
357a0 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
357b0 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
357c0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
357d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
357e0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
357f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35800 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
35810 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35820 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
35830 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
35840 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
35850 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
35860 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
35870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35880 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
35890 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
358a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
358b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e  .**.** <b>Warnin
358c0 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65  g:</b> ^The obje
358d0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
358e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
358f0 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
35900 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35910 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35920 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69  ect.  In a multi
35930 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e  threaded environ
35940 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72  ment,.** an unpr
35950 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35960 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
35970 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61   only be used sa
35980 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71  fely with.** [sq
35990 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
359a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
359b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
359c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
359d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
359e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
359f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
35a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35a10 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
35a20 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
35a30 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
35a40 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
35a50 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
35a60 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
35a70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
35a80 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
35a90 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
35aa0 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ], the behavior 
35ab0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
35ac0 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65  e..** Hence, the
35ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35ae0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
35af0 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  e.** is normally
35b00 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74   only useful wit
35b10 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hin the implemen
35b20 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61  tation of .** [a
35b30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35b40 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
35b50 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  ] or [virtual ta
35b60 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69  bles], not withi
35b70 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61  n.** top-level a
35b80 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e  pplication code.
35b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65  .**.** The these
35ba0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74   routines may at
35bb0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
35bc0 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66   the datatype of
35bd0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
35be0 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  ^For example, if
35bf0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
35c00 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
35c10 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
35c20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
35c30 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
35c40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
35c50 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
35c60 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
35c70 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
35c80 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
35c90 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
35ca0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
35cb0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
35cc0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
35cd0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
35ce0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
35cf0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
35d00 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
35d10 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
35d20 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
35d30 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
35d40 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
35d50 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
35d60 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
35d70 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
35d80 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
35d90 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
35da0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
35db0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
35dc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
35dd0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
35de0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
35df0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
35e00 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
35e10 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
35e20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35e30 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
35e40 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
35e50 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
35e60 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
35e70 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
35e80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
35e90 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35ea0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
35eb0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
35ec0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
35ed0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
35ee0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
35ef0 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
35f00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35f10 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
35f20 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35f30 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35f40 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
35f50 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
35f60 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
35f70 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
35f80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
35f90 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
35fa0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
35fb0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
35fc0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35fd0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35fe0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
35ff0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
36000 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
36010 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
36020 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
36030 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
36040 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
36050 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
36060 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
36070 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
36080 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
36090 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
360a0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
360b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
360c0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
360d0 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
360e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
360f0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
36100 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
36110 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
36120 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
36130 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
36140 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
36150 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
36160 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
36170 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
36180 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
36190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
361a0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
361b0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
361c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
361d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
361e0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
361f0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
36200 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
36210 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
36220 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
36230 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
36240 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
36250 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
36260 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
36270 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
36280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36290 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
362a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
362b0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
362c0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
362d0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
362e0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
362f0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
36300 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
36310 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
36320 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
36330 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
36340 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
36350 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
36360 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36370 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
36380 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
36390 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
363a0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
363b0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
363c0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
363d0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
363e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
363f0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
36400 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
36410 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
36420 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
36430 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
36440 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
36450 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
36460 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
36470 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
36480 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
36490 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
364a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
364b0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
364c0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
364d0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
364e0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
364f0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
36500 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
36510 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
36520 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
36530 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
36540 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
36550 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
36560 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
36570 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
36580 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
36590 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
365a0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
365b0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
365c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
365d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
365e0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
365f0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
36600 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
36610 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
36620 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
36630 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
36640 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
36650 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
36660 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
36670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
36680 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
36690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
366a0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
366b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
366c0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
366d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
366e0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
366f0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
36700 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
36710 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
36720 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
36730 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
36740 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
36750 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
36760 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36770 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
36780 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36790 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
367a0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
367b0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
367c0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
367d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
367e0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
367f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36800 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
36810 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
36820 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
36830 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
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 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
36860 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
36870 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
36880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36890 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
368a0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
368b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
368c0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
368d0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
368e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
368f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
36900 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
36910 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
36920 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
36930 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
36940 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
36950 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
36960 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
36970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
36980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
36990 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
369a0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
369b0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
369c0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
369d0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
369e0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
369f0 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20 74  .  Do not pass t
36a00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
36a10 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
36a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36a30 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
36a40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
36a50 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
36a60 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
36a70 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
36a80 68 65 20 69 6e 70 75 74 20 70 61 72 61 6d 65 74  he input paramet
36a90 65 72 73 20 61 72 65 20 63 6f 72 72 65 63 74 2c  ers are correct,
36aa0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
36ab0 77 69 6c 6c 20 6f 6e 6c 79 0a 2a 2a 20 66 61 69  will only.** fai
36ac0 6c 20 69 66 20 61 6e 20 6f 75 74 2d 6f 66 2d 6d  l if an out-of-m
36ad0 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f 63 63 75  emory error occu
36ae0 72 73 20 64 75 72 69 6e 67 20 61 20 66 6f 72 6d  rs during a form
36af0 61 74 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  at conversion..*
36b00 2a 20 4f 6e 6c 79 20 74 68 65 20 66 6f 6c 6c 6f  * Only the follo
36b10 77 69 6e 67 20 73 75 62 73 65 74 20 6f 66 20 69  wing subset of i
36b20 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
36b30 62 6a 65 63 74 20 74 6f 20 6f 75 74 2d 6f 66 2d  bject to out-of-
36b40 6d 65 6d 6f 72 79 0a 2a 2a 20 65 72 72 6f 72 73  memory.** errors
36b50 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
36b60 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
36b70 75 6d 6e 5f 62 6c 6f 62 28 29 0a 2a 2a 20 3c 6c  umn_blob().** <l
36b80 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
36b90 6e 5f 74 65 78 74 28 29 0a 2a 2a 20 3c 6c 69 3e  n_text().** <li>
36ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36bb0 74 65 78 74 31 36 28 29 0a 2a 2a 20 3c 6c 69 3e  text16().** <li>
36bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36bd0 62 79 74 65 73 28 29 0a 2a 2a 20 3c 6c 69 3e 20  bytes().** <li> 
36be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36bf0 79 74 65 73 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c  ytes16().** </ul
36c00 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 6f 75  >.**.** If an ou
36c10 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
36c20 72 20 6f 63 63 75 72 73 2c 20 74 68 65 6e 20 74  r occurs, then t
36c30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
36c40 66 72 6f 6d 20 74 68 65 73 65 0a 2a 2a 20 72 6f  from these.** ro
36c50 75 74 69 6e 65 73 20 69 73 20 74 68 65 20 73 61  utines is the sa
36c60 6d 65 20 61 73 20 69 66 20 74 68 65 20 63 6f 6c  me as if the col
36c70 75 6d 6e 20 68 61 64 20 63 6f 6e 74 61 69 6e 65  umn had containe
36c80 64 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 20 76 61  d an SQL NULL va
36c90 6c 75 65 2e 0a 2a 2a 20 56 61 6c 69 64 20 53 51  lue..** Valid SQ
36ca0 4c 20 4e 55 4c 4c 20 72 65 74 75 72 6e 73 20 63  L NULL returns c
36cb0 61 6e 20 62 65 20 64 69 73 74 69 6e 67 75 69 73  an be distinguis
36cc0 68 65 64 20 66 72 6f 6d 20 6f 75 74 2d 6f 66 2d  hed from out-of-
36cd0 6d 65 6d 6f 72 79 20 65 72 72 6f 72 73 0a 2a 2a  memory errors.**
36ce0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   by invoking the
36cf0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
36d00 65 28 29 5d 20 69 6d 6d 65 64 69 61 74 65 6c 79  e()] immediately
36d10 20 61 66 74 65 72 20 74 68 65 20 73 75 73 70 65   after the suspe
36d20 63 74 0a 2a 2a 20 72 65 74 75 72 6e 20 76 61 6c  ct.** return val
36d30 75 65 20 69 73 20 6f 62 74 61 69 6e 65 64 20 61  ue is obtained a
36d40 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  nd before any.**
36d50 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
36d60 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
36d70 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  d on the same [d
36d80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36d90 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  on]..*/.const vo
36da0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
36db0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
36dc0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36dd0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
36de0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
36df0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36e00 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
36e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
36e20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36e30 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
36e40 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
36e50 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
36e60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36e70 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
36e80 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
36e90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36ea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36eb0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
36ec0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
36ed0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
36ee0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36ef0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
36f00 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
36f10 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
36f20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36f30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
36f40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
36f50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36f60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
36f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
36f80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
36f90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
36fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36fb0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
36fc0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
36fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
36fe0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
36ff0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
37000 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
37010 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
37020 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37030 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
37040 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
37050 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
37060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37070 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
37080 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
37090 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
370a0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
370b0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
370c0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
370d0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
370e0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
370f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37100 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
37110 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
37120 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
37130 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
37140 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
37150 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
37160 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
37170 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
37180 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
37190 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
371a0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
371b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
371c0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
371d0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
371e0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
371f0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
37200 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
37210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37220 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
37230 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
37240 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
37250 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
37260 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
37270 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
37280 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
37290 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
372a0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
372b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
372c0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
372d0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
372e0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
372f0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
37300 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
37310 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
37320 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
37330 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
37340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
37350 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
37360 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
37370 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
37380 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
37390 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
373a0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
373b0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
373c0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
373d0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
373e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
373f0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
37400 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
37410 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
37420 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
37430 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
37440 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
37450 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
37460 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
37470 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
37480 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
37490 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
374a0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
374b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
374c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
374d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
374e0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
374f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
37500 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
37510 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
37520 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37530 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
37540 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
37550 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
37560 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
37570 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
37580 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
37590 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
375a0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
375b0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
375c0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
375d0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
375e0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
375f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
37600 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
37610 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
37620 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
37630 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
37640 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
37650 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
37660 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
37670 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
37680 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
37690 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
376a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
376b0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
376c0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
376d0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
376e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
376f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
37700 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
37710 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
37720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37730 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
37740 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
37750 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
37760 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
37770 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
37780 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
37790 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
377a0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
377b0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
377c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
377d0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
377e0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
377f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
37800 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
37810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37820 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
37830 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
37840 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
37850 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
37860 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
37870 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
37880 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
37890 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
378a0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
378b0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
378c0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
378d0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
378e0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
378f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
37900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
37910 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
37920 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
37930 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
37940 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
37950 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
37960 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
37970 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
37980 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
37990 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
379a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
379b0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
379c0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
379d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
379e0 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
379f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
37a00 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
37a10 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
37a20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
37a30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
37a40 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
37a50 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
37a60 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37a70 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
37a80 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
37a90 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
37aa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
37ab0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
37ac0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
37ad0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
37ae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
37af0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
37b00 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
37b10 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
37b20 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
37b30 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
37b40 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
37b50 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
37b60 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
37b70 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
37b80 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
37b90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37ba0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
37bb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
37bc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37bd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37be0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
37bf0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
37c00 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
37c10 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
37c20 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
37c30 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
37c40 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37c50 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
37c60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37c70 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
37c80 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
37c90 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
37ca0 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
37cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
37cc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
37cd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37ce0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
37cf0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
37d00 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
37d10 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
37d20 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
37d30 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
37d40 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
37d50 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
37d60 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
37d70 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
37d80 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
37d90 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
37da0 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
37db0 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
37dc0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
37dd0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
37de0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
37df0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
37e00 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
37e10 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
37e20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
37e30 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
37e40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
37e50 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
37e60 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
37e70 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
37e80 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
37e90 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37ea0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
37eb0 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
37ec0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
37ed0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37ee0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
37ef0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
37f00 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
37f10 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
37f20 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
37f30 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
37f40 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
37f50 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
37f60 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
37f70 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
37f80 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
37f90 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
37fa0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37fb0 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
37fc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
37fd0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
37fe0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
37ff0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
38000 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
38010 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
38020 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
38030 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
38040 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
38050 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
38060 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
38070 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
38080 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
38090 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
380a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
380b0 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
380c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
380d0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
380e0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
380f0 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
38100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
38110 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
38120 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
38130 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
38140 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
38150 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
38160 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
38170 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
38180 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
38190 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
381a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
381b0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
381c0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
381d0 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
381e0 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
381f0 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
38200 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
38210 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
38220 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
38230 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
38240 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
38250 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
38260 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
38270 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
38280 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
38290 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
382a0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
382b0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
382c0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
382d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
382e0 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
382f0 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
38300 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
38310 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
38320 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
38330 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
38340 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
38350 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
38360 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
38370 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
38380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
38390 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
383a0 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
383b0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
383c0 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
383d0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
383e0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
383f0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
38400 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
38410 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
38420 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
38430 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
38440 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
38450 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
38460 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
38470 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
38480 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
38490 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
384a0 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
384b0 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
384c0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
384d0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
384e0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
384f0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
38500 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
38510 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
38520 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
38530 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
38540 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
38550 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
38560 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
38570 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
38580 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
38590 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
385a0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
385b0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
385c0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
385d0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
385e0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
385f0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
38600 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
38610 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
38620 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
38630 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
38640 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
38650 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
38660 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
38670 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
38680 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
38690 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
386a0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
386b0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
386c0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
386d0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
386e0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
386f0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
38700 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
38710 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
38720 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
38730 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL functio