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

Artifact 91ebe5f8b4e6595325110fb23efe6cc70dfe53d394d2dd31c8b6cdf6a98325e0:


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 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
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 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e 5f  ITE_IOERR_BEGIN_
5730: 41 54 4f 4d 49 43 20 20 20 20 20 20 28 53 51 4c  ATOMIC      (SQL
5740: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 39 3c  ITE_IOERR | (29<
5750: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5760: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49 54  ITE_IOERR_COMMIT
5770: 5f 41 54 4f 4d 49 43 20 20 20 20 20 28 53 51 4c  _ATOMIC     (SQL
5780: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 30 3c  ITE_IOERR | (30<
5790: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
57a0: 49 54 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42 41  ITE_IOERR_ROLLBA
57b0: 43 4b 5f 41 54 4f 4d 49 43 20 20 20 28 53 51 4c  CK_ATOMIC   (SQL
57c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 31 3c  ITE_IOERR | (31<
57d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
57e0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
57f0: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5800: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5810: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5820: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5830: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5840: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5850: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5860: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
5870: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
5880: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5890: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
58a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58b0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
58c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58d0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58e0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58f0: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5900: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5910: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5930: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5940: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5950: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
5960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5970: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
5980: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5990: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59b0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
59d0: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5a00: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5a10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5a40: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5a50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
5a80: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
5a90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5ac0: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5ad0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5b00: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5b10: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5b20: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5b30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b40: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b80: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ba0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5bc0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5bd0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5bf0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5c10: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c50: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5c80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c90: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5ca0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cb0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cd0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5ce0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5cf0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5d20: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5d30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5d40: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5d50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d60: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5d70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d80: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5da0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5db0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5dc0: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5de0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5df0: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5e00: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5e20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5e30: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5e40: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5e60: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5e70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5e80: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5ee0: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5ef0: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5f00: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5f10: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5f20: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5f30: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5f40: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5f50: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5f60: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5f70: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5f80: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5f90: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5fa0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5fb0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5fc0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5fd0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5fe0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5ff0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
6000: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
6010: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
6020: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6030: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6040: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
6050: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
6060: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
6070: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6080: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6090: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
60a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
60b0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
60c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
60d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
60f0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6100: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6110: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6120: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6130: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6140: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6150: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6160: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
6170: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
6180: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
6190: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61a0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
61b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
61c0: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
61d0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61e0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6200: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6210: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6220: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6230: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6250: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6260: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6290: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
62a0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
62d0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
62e0: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6310: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6320: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6350: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6360: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
6370: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6380: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6390: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
63a0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
63b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
63c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
63d0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
63e0: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
63f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6400: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6410: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6420: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6430: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6440: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6450: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
6460: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
6470: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6480: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6490: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
64a0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
64b0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
64c0: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
64d0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
64e0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
64f0: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6500: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6510: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6520: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6530: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6540: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6550: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6560: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
6570: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6580: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6590: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
65a0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
65b0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
65c0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
65d0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
65e0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
65f0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6600: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6610: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6620: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6630: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6640: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6650: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6660: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6670: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6680: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6690: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
66a0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
66b0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
66c0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
66d0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6700: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6710: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6720: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6730: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6740: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6750: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6760: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6770: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6780: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6790: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
67a0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
67b0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
67c0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
67d0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
67e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
67f0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6800: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6810: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6820: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6830: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6840: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6850: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6860: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6870: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6880: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6890: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
68a0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
68b0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
68c0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
68d0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
68e0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
68f0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6900: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6910: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6920: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6930: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6940: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6950: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6960: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6970: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6980: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6990: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
69a0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
69b0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
69c0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
69d0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
69e0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
69f0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6a00: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6a10: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6a20: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6a30: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6a40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6a50: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6a60: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6a70: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
6a80: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6a90: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6aa0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6ab0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6ac0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6ad0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6ae0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6af0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6b00: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6b10: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6b20: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6b30: 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  vileges..**.** T
6b40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6b50: 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f  BATCH_ATOMIC pro
6b60: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6b70: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
6b80: 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75  ** filesystem su
6b90: 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c  pports doing mul
6ba0: 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72  tiple write oper
6bb0: 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c  ations atomicall
6bc0: 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20  y when those.** 
6bd0: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
6be0: 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 62   are bracketed b
6bf0: 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  y [SQLITE_FCNTL_
6c00: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
6c10: 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  TE] and.** [SQLI
6c20: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
6c30: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
6c40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c70: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c90: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ce0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6d00: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6d10: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d30: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d50: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d70: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6d80: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6da0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6dc0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6de0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6df0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6e10: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e40: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6e50: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6e60: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6e70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6e80: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6e90: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6eb0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6ec0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6ed0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6ee0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6ef0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6f00: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
6f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f20: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
6f30: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
6f40: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6f50: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6f60: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6f70: 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a  0x00004000../*.*
6f80: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6f90: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6fa0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6fb0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6fc0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6fd0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6fe0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6ff0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
7000: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7010: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
7020: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
7030: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7040: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
7050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7060: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
7070: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7080: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
7090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
70a0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
70b0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
70c0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
70d0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
70e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
70f0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
7100: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
7110: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
7120: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
7130: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
7140: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
7150: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
7160: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7170: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
7180: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
7190: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
71a0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
71b0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
71c0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
71d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
71e0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
71f0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
7200: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
7210: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
7220: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
7230: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
7240: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
7250: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
7260: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
7270: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7280: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
7290: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
72b0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
72c0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
72d0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
72e0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
72f0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
7300: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
7310: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
7320: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7330: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7340: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7350: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7360: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7370: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7380: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7390: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
73a0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
73b0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
73c0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
73d0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
73e0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
73f0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
7400: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
7410: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
7420: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
7430: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7440: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7450: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7460: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7470: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7480: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7490: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
74a0: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
74b0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
74c0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
74d0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
74e0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
74f0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
7500: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
7510: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
7520: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
7530: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7540: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7550: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7560: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7570: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7580: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
75a0: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
75b0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
75c0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
75d0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
75e0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
75f0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
7600: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
7610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7620: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
7630: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7650: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7660: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7670: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7680: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
76a0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
76b0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
76c0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
76d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
76e0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
76f0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
7700: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
7710: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7720: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7730: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7740: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7750: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7760: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7770: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7780: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7790: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
77a0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
77b0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
77c0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
77d0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
77e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
77f0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7800: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7810: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7820: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7830: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7840: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7850: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7860: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7870: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7880: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7890: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
78a0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
78b0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
78c0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
78d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
78e0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
78f0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7900: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7910: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7920: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7930: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7940: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7950: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7960: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7970: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7980: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7990: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
79a0: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
79b0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
79c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
79d0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
79e0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
79f0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7a00: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7a10: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7a20: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7a30: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7a40: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7a50: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7a60: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7a70: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7a80: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7a90: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7aa0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7ab0: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7ac0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7ad0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7ae0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7af0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7b00: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7b10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7b20: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7b30: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7b40: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7b50: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7b60: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7b70: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7b80: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7b90: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7ba0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7bb0: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7bc0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7bd0: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7be0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7bf0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7c00: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7c10: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7c20: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7c30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7c40: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7c50: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7c60: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7c70: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7c80: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7c90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7ca0: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7cb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7cc0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7cd0: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7ce0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7cf0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7d00: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7d10: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7d20: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7d30: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7d40: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7d50: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7d60: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7d70: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7d80: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7d90: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7da0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7db0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7dc0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7dd0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7de0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7e00: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7e10: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7e20: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7e30: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7e40: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7e50: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7e60: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7e70: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7e80: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7e90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7ea0: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7eb0: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7ec0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7ed0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7ee0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7ef0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7f00: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7f10: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7f20: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7f30: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7f40: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7f50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7f60: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7f70: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7f80: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7f90: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7fa0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7fb0: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7fc0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7fd0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7fe0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ff0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
8000: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
8010: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
8020: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
8030: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
8040: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
8050: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
8060: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
8070: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
8080: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
8090: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
80a0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
80b0: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
80c0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
80d0: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
80e0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
80f0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
8100: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
8110: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
8120: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
8130: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
8140: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
8150: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
8160: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
8170: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
8180: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
8190: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
81a0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
81b0: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
81c0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
81d0: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
81e0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
81f0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
8200: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
8210: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
8220: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
8230: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
8240: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
8250: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
8260: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
8270: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8280: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
8290: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
82a0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
82b0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
82c0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
82d0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
82e0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
82f0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
8300: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
8310: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
8320: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8330: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8340: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8350: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8360: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8370: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8380: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8390: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
83a0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
83b0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
83c0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
83d0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
83e0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
83f0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
8400: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
8410: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
8420: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8430: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8440: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8450: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8460: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8470: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8480: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8490: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
84a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
84b0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
84c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
84d0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
84e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
84f0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
8500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8510: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
8520: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8530: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8550: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8560: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8570: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8580: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8590: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
85a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
85b0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
85c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
85d0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
8600: 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c  WHEN_OPEN].** <l
8610: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8620: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8630: 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RITE].** <li> [S
8640: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8650: 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TABLE].** <li> [
8660: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
8670: 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f  CH_ATOMIC].** </
8680: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8690: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
86a0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
86b0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
86c0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
86d0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
86e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
86f0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8700: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8710: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8720: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8730: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8740: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8750: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8760: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8770: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8780: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8790: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
87a0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
87b0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
87c0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
87d0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
87e0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
87f0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8800: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8810: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8820: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8830: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8840: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8850: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8860: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8870: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8880: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8890: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
88a0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
88b0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
88c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
88d0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
88e0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
88f0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
8900: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
8910: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
8920: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
8930: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8940: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8950: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8960: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8970: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8980: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8990: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
89a0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
89b0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
89c0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
89d0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
89e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
89f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
8a00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
8a10: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8a20: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
8a30: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8a40: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8a50: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8a60: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8a70: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8a80: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8a90: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8aa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8ab0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8ac0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8ad0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8ae0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8af0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
8b00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8b10: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
8b20: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
8b30: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8b40: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8b50: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8b60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b70: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8b80: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8b90: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8bb0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8bc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8bd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
8be0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
8bf0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8c00: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8c10: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
8c20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8c30: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8c40: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8c50: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8c60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8c70: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8c80: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8c90: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8ca0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8cb0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8cc0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8cd0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
8ce0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
8cf0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
8d00: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
8d10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
8d20: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8d30: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8d40: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8d50: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8d60: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8d70: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8d80: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8d90: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8da0: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8db0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8dc0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8dd0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
8de0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
8df0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8e00: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
8e10: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
8e20: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
8e30: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8e40: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8e50: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8e60: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8e70: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e80: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8e90: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8ea0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8eb0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8ec0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8ed0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8ee0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
8ef0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
8f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
8f10: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8f20: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
8f30: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8f40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8f50: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8f60: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8f70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8f80: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8f90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8fa0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8fb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8fc0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8fd0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
8fe0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8ff0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
9000: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
9010: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
9020: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
9030: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
9040: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
9050: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
9060: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9070: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
9080: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
9090: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
90a0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
90b0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
90c0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
90d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
90e0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
90f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
9100: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
9110: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
9120: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
9130: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
9140: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
9150: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
9160: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
9170: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
9180: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
9190: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
91a0: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
91b0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
91c0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
91d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
91e0: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
91f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9200: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
9210: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
9220: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
9230: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
9240: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
9250: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9260: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
9270: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
9280: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
9290: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
92a0: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
92b0: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
92c0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
92d0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
92e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
92f0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
9300: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
9310: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
9320: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
9330: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
9340: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
9350: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9360: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
9370: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9390: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
93a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
93b0: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
93c0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
93d0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
93e0: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
93f0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
9400: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
9410: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
9420: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
9430: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
9440: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
9470: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
9480: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
9490: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
94a0: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
94b0: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
94c0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
94d0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
94e0: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
94f0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
9500: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
9510: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
9520: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
9530: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
9540: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
9550: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
9560: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
9570: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9580: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9590: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
95a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
95b0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
95c0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
95d0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
95e0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
95f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9600: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
9610: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9620: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9630: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9640: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9650: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
9660: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9670: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9680: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9690: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
96a0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
96b0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
96c0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
96d0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
96e0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
96f0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9700: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
9710: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
9720: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
9730: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
9740: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
9750: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9760: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9770: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
9780: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9790: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
97a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
97b0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
97c0: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
97d0: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
97e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
97f0: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
9800: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9810: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
9820: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9830: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
9840: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
9850: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9860: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9870: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
9880: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
9890: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
98a0: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
98b0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
98c0: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
98d0: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
98e0: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
98f0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
9900: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9910: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9920: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9930: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
9940: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
9950: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9960: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9970: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
9980: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
9990: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
99a0: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
99b0: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
99c0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
99d0: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
99e0: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
99f0: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
9a00: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
9a10: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
9a20: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
9a30: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
9a40: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
9a50: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9a60: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9a70: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
9a80: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9a90: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9aa0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9ab0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ac0: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
9ad0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9ae0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9af0: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9b00: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9b10: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
9b20: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9b30: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9b40: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9b50: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9b60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9b70: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9b80: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
9b90: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9ba0: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
9bb0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9bc0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9bd0: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
9be0: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
9bf0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
9c00: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
9c10: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
9c20: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
9c30: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
9c40: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
9c50: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9c60: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
9c70: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9c80: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9c90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9ca0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
9cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9cc0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9cd0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9ce0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
9cf0: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
9d00: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9d10: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9d20: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9d30: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9d40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9d50: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
9d60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9d70: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9d80: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9d90: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
9da0: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
9db0: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
9dc0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
9dd0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
9de0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
9df0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
9e00: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
9e10: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
9e20: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
9e30: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
9e40: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
9e50: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
9e60: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
9e70: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
9e80: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
9e90: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
9ea0: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
9eb0: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
9ec0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
9ed0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
9ee0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
9ef0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
9f00: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
9f10: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
9f20: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
9f30: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
9f40: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
9f50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
9f60: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
9f70: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
9f80: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
9f90: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
9fa0: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
9fb0: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
9fc0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
9fd0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
9fe0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
9ff0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
a000: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
a010: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
a020: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
a030: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
a040: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
a050: 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77  teger is the new
a060: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
a070: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
a080: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
a090: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
a0a0: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
a0b0: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
a0c0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
a0d0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
a0e0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
a0f0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
a100: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
a110: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
a120: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
a130: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
a140: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
a150: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
a160: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
a170: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
a180: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
a190: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a1a0: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
a1b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a1c0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
a1d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a1e0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a1f0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a200: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
a210: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
a220: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
a230: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
a240: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
a250: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a260: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
a270: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
a280: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
a290: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
a2a0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
a2b0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
a2c0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
a2d0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
a2e0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a2f0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
a300: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
a310: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
a320: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
a330: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
a340: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
a350: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
a360: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
a370: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
a380: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
a390: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
a3a0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
a3b0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
a3c0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
a3d0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
a3e0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3f0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
a400: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
a410: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a420: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a430: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a440: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a450: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a460: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a470: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a480: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a490: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a4a0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a4b0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a4c0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a4d0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a4e0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a4f0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a500: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a510: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a520: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a530: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a540: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a550: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a560: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a570: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a580: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a590: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a5a0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a5b0: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a5c0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a5d0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a5e0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a5f0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a600: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a610: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a620: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a630: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a640: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a650: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a660: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a670: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a680: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a690: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a6a0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a6b0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a6c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a6d0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a6e0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a6f0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a700: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a710: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a720: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a730: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a740: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a750: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a760: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a770: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a780: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a790: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a7a0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a7b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a7c0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a7d0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a7e0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a7f0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a800: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a810: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a820: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a830: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a840: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a850: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a860: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a870: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a880: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a890: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a8a0: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a8b0: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a8c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a8d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a8e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a8f0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a900: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a910: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a920: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a930: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a940: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a950: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a960: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a970: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a980: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a990: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a9a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a9b0: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a9c0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a9d0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a9e0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a9f0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
aa00: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
aa10: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
aa20: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
aa30: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
aa40: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
aa50: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
aa60: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
aa70: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
aa80: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
aa90: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
aaa0: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
aab0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
aac0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
aad0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
aae0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
aaf0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
ab00: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
ab10: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
ab20: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
ab30: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
ab40: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
ab50: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
ab60: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
ab70: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
ab80: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
ab90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aba0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
abb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
abc0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
abd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e  NTER] opcode fin
abe0: 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ds a pointer to 
abf0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a  the top-level.**
ac00: 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74   [VFSes] current
ac10: 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68  ly in use.  ^(Th
ac20: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a  e argument X in.
ac30: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  ** sqlite3_file_
ac40: 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54  control(db,SQLIT
ac50: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
ac60: 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a  TER,X) must be.*
ac70: 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69  * of type "[sqli
ac80: 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54  te3_vfs] **".  T
ac90: 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c  his opcodes will
aca0: 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20   set *X.** to a 
acb0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
acc0: 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a  op-level VFS.)^.
acd0: 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61  ** ^When there a
ace0: 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20  re multiple VFS 
acf0: 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61  shims in the sta
ad00: 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ck, this opcode 
ad10: 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70  finds the.** upp
ad20: 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c  er-most shim onl
ad30: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
ad40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad50: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
ad60: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
ad70: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
ad80: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
ad90: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
ada0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
adb0: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
adc0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
add0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
ade0: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
adf0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
ae00: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
ae10: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
ae20: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
ae30: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
ae40: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ae50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ae60: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
ae70: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
ae80: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
ae90: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
aea0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
aeb0: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
aec0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
aed0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
aee0: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
aef0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
af00: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
af10: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
af20: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
af30: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
af40: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
af50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
af60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
af70: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
af80: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
af90: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
afa0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
afb0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
afc0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
afd0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
afe0: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
aff0: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
b000: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
b010: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
b020: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
b030: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
b040: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
b050: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
b060: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b070: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b080: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
b090: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b0a0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
b0b0: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
b0c0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
b0d0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b0e0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b0f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b100: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
b110: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
b120: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
b130: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
b140: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
b150: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
b160: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
b170: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
b180: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
b190: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
b1a0: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
b1b0: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
b1c0: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
b1d0: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
b1e0: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
b1f0: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
b200: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b210: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b220: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
b230: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
b240: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
b250: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
b260: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
b270: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
b280: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
b290: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
b2a0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
b2b0: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
b2c0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
b2d0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
b2e0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
b2f0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b300: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b310: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
b320: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
b330: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
b340: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
b350: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
b360: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
b370: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
b380: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
b390: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b3a0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b3b0: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
b3c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b3d0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b3e0: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b3f0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b400: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b410: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b420: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b430: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b440: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b450: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b460: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b470: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b480: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b490: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b4a0: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b4b0: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b4c0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b4d0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b4e0: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b4f0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b500: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b510: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b520: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b530: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b540: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b550: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b560: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b570: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b580: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b590: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b5a0: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b5b0: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b5c0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b5d0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b5e0: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b5f0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b600: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b610: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b620: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b630: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
b640: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
b650: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b660: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b670: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
b680: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
b690: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b6a0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
b6b0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b6c0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
b6d0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
b6e0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
b6f0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
b700: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
b710: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
b720: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
b730: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
b740: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
b750: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
b760: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
b770: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
b780: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
b790: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
b7a0: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
b7b0: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
b7c0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
b7d0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b7e0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
b7f0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
b800: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
b810: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
b820: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
b830: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
b840: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b850: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b860: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b870: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b880: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b890: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
b8a0: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
b8b0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b8c0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
b8d0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
b8e0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
b8f0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b900: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b910: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
b920: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
b930: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
b940: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
b950: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
b960: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
b970: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
b980: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
b990: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
b9a0: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
b9b0: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
b9c0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
b9d0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
b9e0: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
b9f0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
ba00: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
ba10: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
ba20: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
ba30: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
ba40: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
ba50: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
ba60: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
ba70: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
ba80: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
ba90: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
baa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bab0: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
bac0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bad0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
bae0: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
baf0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
bb00: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
bb10: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
bb20: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
bb30: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
bb40: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
bb50: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
bb60: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
bb70: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
bb80: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
bb90: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
bba0: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
bbb0: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
bbc0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
bbd0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
bbe0: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
bbf0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
bc00: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bc10: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
bc20: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
bc30: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
bc40: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
bc50: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bc60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
bc70: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
bc80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
bc90: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
bca0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
bcb0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
bcc0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
bcd0: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
bce0: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
bcf0: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
bd00: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
bd10: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
bd20: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
bd30: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
bd40: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
bd50: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
bd60: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
bd70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bd80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
bd90: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
bda0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bdb0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
bdc0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
bdd0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
bde0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
bdf0: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
be00: 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  dle associated w
be10: 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c  ith a file handl
be20: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a  e.  This file.**
be30: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
be40: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
be50: 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   as a pointer to
be60: 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68   a native file h
be70: 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69  andle and.** wri
be80: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e  tes the resultin
be90: 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a  g value there..*
bea0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
beb0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
bec0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
bed0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bee0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bef0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
bf00: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
bf10: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
bf20: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
bf30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
bf40: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
bf50: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
bf60: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
bf70: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
bf80: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
bf90: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
bfa0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
bfb0: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
bfc0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
bfd0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
bfe0: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
bff0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c000: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c010: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c030: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
c040: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
c050: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
c060: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
c070: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
c080: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
c090: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
c0a0: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
c0b0: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
c0c0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
c0d0: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
c0e0: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
c0f0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
c100: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
c110: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
c120: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
c130: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
c140: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
c150: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
c160: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
c170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c180: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
c190: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c1a0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
c1b0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c1c0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
c1d0: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
c1e0: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c1f0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c200: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
c210: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c230: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c240: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
c250: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
c260: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
c270: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
c280: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
c290: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
c2a0: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
c2b0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c2c0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
c2d0: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a   opcode.  .**.**
c2e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c2f0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c300: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74  _WRITE]].** If t
c310: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c320: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c330: 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75  ITE] opcode retu
c340: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74  rns SQLITE_OK, t
c350: 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20  hen.** the file 
c360: 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c  descriptor is pl
c370: 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20 77  aced in "batch w
c380: 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63  rite mode", whic
c390: 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73  h.** means all s
c3a0: 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20  ubsequent write 
c3b0: 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20  operations will 
c3c0: 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64 20  be deferred and 
c3d0: 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c  done.** atomical
c3e0: 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b  ly at the next [
c3f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c400: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c410: 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74  ].  Systems.** t
c420: 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  hat do not suppo
c430: 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20  rt batch atomic 
c440: 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75  writes will retu
c450: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c460: 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e  ND..** ^Followin
c470: 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 53  g a successful S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c490: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61  N_ATOMIC_WRITE a
c4a0: 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74  nd prior to.** t
c4b0: 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49  he closing [SQLI
c4c0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c4d0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72  ATOMIC_WRITE] or
c4e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c4f0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c500: 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65  C_WRITE], SQLite
c510: 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f   will make.** no
c520: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 63   VFS interface c
c530: 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  alls on the same
c540: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c550: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a  file descriptor.
c560: 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63 61  ** except for ca
c570: 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69 74  lls to the xWrit
c580: 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65  e method and the
c590: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c5a0: 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51  thod.** with [SQ
c5b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
c5c0: 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  HINT]..**.** <li
c5d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c5e0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c5f0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
c600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c610: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
c620: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
c630: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
c640: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
c650: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
c660: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
c670: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c680: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c690: 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65  ] to be performe
c6a0: 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a  d atomically..**
c6b0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
c6c0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
c6d0: 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e  TE_OK] if and on
c6e0: 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65 73  ly if the writes
c6f0: 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72   were.** all per
c700: 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66 75  formed successfu
c710: 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65 65  lly and have bee
c720: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70  n committed to p
c730: 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67  ersistent storag
c740: 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  e..** ^Regardles
c750: 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
c760: 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65 73  not it is succes
c770: 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20  sful, this file 
c780: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a  control takes.**
c790: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
c7a0: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
c7b0: 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20  h write mode so 
c7c0: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
c7d0: 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65  ent.** write ope
c7e0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
c7f0: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
c800: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
c810: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
c820: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
c830: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
c840: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
c850: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
c860: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c870: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
c880: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c890: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
c8a0: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  K_ATOMIC_WRITE]]
c8b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c8c0: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c8e0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c8f0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c900: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c910: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c920: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c930: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c940: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
c950: 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  o be rolled back
c960: 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20  ..** ^This file 
c970: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68  control takes th
c980: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
c990: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
c9a0: 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20  rite mode.** so 
c9b0: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
c9c0: 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74  ent write operat
c9d0: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
c9e0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
c9f0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
ca00: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
ca10: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
ca20: 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a  WRITE without.**
ca30: 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
ca40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c  ful call to [SQL
ca50: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
ca60: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
ca70: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
ca80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ca90: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
caa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
cab0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
cac0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
cad0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
cae0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
caf0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
cb00: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
cb10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
cb20: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
cb30: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
cb40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
cb50: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
cb60: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
cb70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
cb80: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
cb90: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
cba0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
cbb0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
cbc0: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cbe0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
cbf0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
cc10: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
cc20: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cc30: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
cc40: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
cc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc60: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
cc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
cc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cc90: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
cca0: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
ccb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ccc0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
ccd0: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
cce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ccf0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
cd00: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
cd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cd20: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
cd30: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
cd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cd50: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
cd60: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
cd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd80: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
cd90: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
cda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
cdb0: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
cdc0: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
cdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
cde0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
cdf0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
ce10: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
ce20: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ce40: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
ce50: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ce70: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
ce80: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
ce90: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
cea0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
ceb0: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
cec0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
ced0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cee0: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
cef0: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
cf10: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
cf20: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
cf30: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
cf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf50: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
cf60: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf80: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
cf90: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
cfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfb0: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
cfc0: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64             30.#d
cfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfe0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cff0: 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65  WRITE     31.#de
d000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d010: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
d020: 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66  WRITE    32.#def
d030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d040: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
d050: 5f 57 52 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64  _WRITE  33../* d
d060: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
d070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d080: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
d090: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d0a0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d0b0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d0c0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
d0d0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
d0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
d0f0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
d100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
d110: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d120: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
d130: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
d140: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
d150: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
d160: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
d170: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
d180: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
d190: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
d1a0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
d1b0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
d1c0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
d1d0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
d1e0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
d1f0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
d200: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
d210: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
d220: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
d230: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
d240: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d250: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
d260: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
d270: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
d280: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
d290: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
d2a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
d2b0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
d2c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d2d0: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
d2e0: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
d2f0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
d300: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
d310: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
d320: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
d330: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
d340: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
d350: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
d360: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
d370: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
d380: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
d390: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
d3a0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
d3b0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
d3c0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
d3d0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
d3e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d3f0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d400: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
d410: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
d420: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
d430: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
d440: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
d450: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
d460: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
d470: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
d480: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
d490: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
d4a0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
d4b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
d4c0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
d4d0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d4e0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
d4f0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
d500: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
d510: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
d520: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
d530: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
d540: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
d550: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
d560: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
d570: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
d580: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
d590: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
d5a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
d5b0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
d5c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
d5d0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
d5e0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
d5f0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
d600: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
d610: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
d620: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
d630: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
d640: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
d650: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
d660: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
d670: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
d680: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
d690: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
d6a0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
d6b0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
d6c0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
d6d0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
d6e0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
d6f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
d700: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
d710: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
d720: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
d730: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
d740: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
d750: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
d760: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
d770: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
d780: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
d790: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
d7a0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
d7b0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
d7c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
d7d0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
d7e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
d7f0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
d800: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
d810: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
d820: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
d830: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
d840: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
d850: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
d860: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
d870: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
d880: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
d890: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
d8a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
d8b0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
d8c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
d8d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
d8e0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
d8f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
d900: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
d910: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
d920: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
d930: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
d940: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
d950: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
d960: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
d970: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
d980: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
d990: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
d9a0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
d9b0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
d9c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
d9d0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
d9e0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
d9f0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
da00: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
da10: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
da20: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
da30: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
da40: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
da50: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
da60: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
da70: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
da80: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
da90: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
daa0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
dab0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
dac0: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
dad0: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
dae0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
daf0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
db00: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
db10: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
db20: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
db30: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
db40: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
db50: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
db60: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
db70: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
db80: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
db90: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
dba0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
dbb0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
dbc0: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
dbd0: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
dbe0: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
dbf0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
dc00: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
dc10: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
dc20: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
dc30: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
dc40: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
dc50: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
dc60: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
dc70: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
dc80: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
dc90: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
dca0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
dcb0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
dcc0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
dcd0: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
dce0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
dcf0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
dd00: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
dd10: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
dd20: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
dd30: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
dd40: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
dd50: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
dd60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
dd70: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
dd80: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
dd90: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
dda0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
ddb0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
ddc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ddd0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
dde0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ddf0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
de00: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
de10: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
de20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
de30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
de40: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
de50: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
de60: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
de70: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
de80: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
de90: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
dea0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
deb0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
dec0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
ded0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
dee0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
def0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
df00: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
df10: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
df20: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
df30: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
df40: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
df50: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
df60: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
df70: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
df80: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
df90: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
dfa0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
dfb0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
dfc0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
dfd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
dfe0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
dff0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
e000: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
e010: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e020: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
e030: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
e040: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
e050: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
e060: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e070: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
e080: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e090: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
e0a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e0b0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
e0c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e0d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
e0e0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
e0f0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
e100: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
e110: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
e120: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
e130: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
e140: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
e150: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
e160: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
e170: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
e180: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
e190: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
e1a0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
e1b0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
e1c0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
e1d0: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
e1e0: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
e1f0: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
e200: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
e210: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
e220: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
e230: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
e240: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
e250: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
e260: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
e270: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
e280: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
e290: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
e2a0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
e2b0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
e2c0: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
e2d0: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
e2e0: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
e2f0: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
e300: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
e310: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
e320: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
e330: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
e340: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
e350: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e360: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e370: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
e380: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
e390: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
e3a0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
e3b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
e3c0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
e3d0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
e3e0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
e3f0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
e400: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
e410: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
e420: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
e430: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
e440: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
e450: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
e460: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
e470: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
e480: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
e490: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e4a0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
e4b0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
e4c0: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
e4d0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
e4e0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
e4f0: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
e500: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
e510: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
e520: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
e530: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
e540: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
e550: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
e560: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e570: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
e580: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
e590: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
e5a0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
e5b0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
e5c0: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
e5d0: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
e5e0: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
e5f0: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
e600: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
e610: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
e620: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
e630: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
e640: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
e650: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
e660: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
e670: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
e680: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
e690: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
e6a0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
e6b0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
e6c0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
e6d0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
e6e0: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
e6f0: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
e700: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
e710: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
e720: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
e730: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
e740: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
e750: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
e760: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e770: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
e780: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
e790: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
e7a0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
e7b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
e7c0: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
e7d0: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
e7e0: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
e7f0: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
e800: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
e810: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
e820: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
e830: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
e840: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
e850: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
e860: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
e870: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
e880: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
e890: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
e8a0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
e8b0: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
e8c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
e8d0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
e8e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
e8f0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
e900: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
e910: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
e920: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
e930: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
e940: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
e950: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
e960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
e970: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
e980: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
e990: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
e9a0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
e9b0: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
e9c0: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
e9d0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
e9e0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
e9f0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
ea00: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
ea10: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
ea20: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
ea30: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
ea40: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
ea50: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
ea60: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
ea70: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
ea80: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
ea90: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
eaa0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
eab0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
eac0: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
ead0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
eae0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
eaf0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
eb00: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
eb10: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
eb20: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
eb30: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
eb40: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
eb50: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
eb60: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
eb70: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
eb80: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
eb90: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
eba0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
ebb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
ebc0: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
ebd0: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
ebe0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
ebf0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
ec00: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
ec10: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
ec20: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
ec30: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
ec40: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
ec50: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
ec60: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
ec70: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
ec80: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
ec90: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
eca0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
ecb0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
ecc0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
ecd0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
ece0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
ecf0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
ed00: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
ed10: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
ed20: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
ed30: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
ed40: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
ed50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
ed60: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
ed70: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ed80: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
ed90: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
eda0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
edb0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
edc0: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
edd0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
ede0: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
edf0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ee00: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
ee10: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
ee20: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
ee30: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
ee40: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
ee50: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
ee60: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
ee70: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
ee80: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
ee90: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
eea0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
eeb0: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
eec0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
eed0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
eee0: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
eef0: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
ef00: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
ef10: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
ef20: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
ef30: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
ef40: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
ef50: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
ef60: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
ef70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
ef80: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
ef90: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
efa0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
efb0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
efc0: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
efd0: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
efe0: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
eff0: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
f000: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
f010: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
f020: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
f030: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
f040: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
f050: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
f060: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
f070: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
f080: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
f090: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
f0a0: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
f0b0: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
f0c0: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
f0d0: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
f0e0: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
f0f0: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
f100: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
f110: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
f120: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
f130: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
f140: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
f150: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
f160: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
f170: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
f180: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
f190: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
f1a0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
f1b0: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
f1c0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
f1d0: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
f1e0: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
f1f0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
f200: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
f210: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
f220: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
f230: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
f240: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
f250: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
f260: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
f270: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
f280: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
f290: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
f2a0: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
f2b0: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
f2c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
f2d0: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
f2e0: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
f2f0: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
f300: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
f310: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
f320: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
f330: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
f340: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
f350: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
f360: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
f370: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
f380: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
f390: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
f3a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
f3b0: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
f3c0: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
f3d0: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
f3e0: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
f3f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
f400: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
f410: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
f420: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
f430: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
f440: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
f450: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
f460: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
f470: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
f480: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
f490: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
f4a0: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
f4b0: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
f4c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f4d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
f4e0: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
f4f0: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
f500: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
f510: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
f520: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
f530: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
f540: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
f550: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
f560: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
f570: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
f580: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
f590: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
f5a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
f5b0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
f5c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f5d0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
f5e0: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
f5f0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
f600: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
f610: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
f620: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
f630: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
f640: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
f650: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
f660: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
f670: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
f680: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
f690: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
f6a0: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
f6b0: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
f6c0: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
f6d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
f6e0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
f6f0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
f700: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
f710: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
f720: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f730: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
f740: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
f750: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
f760: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
f770: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
f780: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
f790: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
f7a0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
f7b0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
f7c0: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
f7d0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f7e0: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
f7f0: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
f800: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
f810: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
f820: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
f830: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
f840: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
f850: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
f860: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
f870: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
f880: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f890: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
f8a0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f8b0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
f8c0: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
f8d0: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
f8e0: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
f8f0: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
f900: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
f910: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f920: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
f930: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
f940: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f950: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
f960: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f970: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f980: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
f990: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
f9a0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
f9b0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f9c0: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
f9d0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
f9e0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
f9f0: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
fa00: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
fa10: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
fa20: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
fa30: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74   appended in fut
fa40: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
fa50: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
fa60: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
fa70: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
fa80: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
fa90: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
faa0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
fab0: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
fac0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
fad0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
fae0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
faf0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
fb00: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
fb10: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
fb20: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
fb30: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
fb40: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
fb50: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
fb60: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
fb70: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
fb80: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
fb90: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
fba0: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
fbb0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
fbc0: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
fbd0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
fbe0: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
fbf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
fc00: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
fc10: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
fc20: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
fc30: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
fc40: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
fc50: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
fc60: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
fc70: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
fc80: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
fc90: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
fca0: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
fcb0: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
fcc0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
fcd0: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
fce0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
fcf0: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
fd00: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
fd10: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
fd20: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
fd30: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
fd40: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
fd50: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
fd60: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
fd70: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
fd80: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
fd90: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
fda0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
fdb0: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
fdc0: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
fdd0: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
fde0: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
fdf0: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
fe00: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
fe10: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
fe20: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
fe30: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
fe40: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
fe50: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
fe60: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
fe70: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
fe80: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
fe90: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
fea0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
feb0: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
fec0: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
fed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
fee0: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
fef0: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
ff00: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ff10: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
ff20: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
ff30: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
ff40: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
ff50: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
ff60: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
ff70: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
ff80: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
ff90: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
ffa0: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
ffb0: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
ffc0: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
ffd0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ffe0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
fff0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
10000 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
10010 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
10020 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10030 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
10040 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
10050 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
10060 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
10070 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
10080 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10090 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
100a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
100b0 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
100c0 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
100d0 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
100e0 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
100f0 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e  .** was given on
10100 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10110 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
10120 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
10130 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
10140 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
10150 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
10160 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
10170 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
10180 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
10190 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
101a0 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
101b0 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
101c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
101d0 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
101e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
101f0 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
10200 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
10210 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
10220 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
10230 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10240 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
10250 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
10260 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
10270 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
10280 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
10290 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
102a0 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
102b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
102c0 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
102d0 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
102e0 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
102f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
10300 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
10310 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
10320 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
10330 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
10340 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
10350 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
10360 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
10370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10380 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
10390 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
103a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
103b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
103c0 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
103d0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
103e0 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
103f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10400 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
10410 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
10420 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
10430 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
10440 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10450 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
10460 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
10470 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
10480 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
10490 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
104a0 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
104b0 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
104c0 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
104d0 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
104e0 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
104f0 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
10500 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
10510 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
10520 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
10530 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10540 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
10550 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
10560 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
10570 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
10580 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
10590 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
105a0 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
105b0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
105c0 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
105d0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
105e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
105f0 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
10600 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
10610 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10620 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
10630 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
10640 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10650 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
10660 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
10670 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
10680 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
10690 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
106a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
106b0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
106c0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
106d0 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
106e0 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
106f0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10700 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
10710 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
10720 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
10730 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
10740 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10750 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
10760 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
10770 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
10780 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
10790 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
107a0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
107b0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
107c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
107d0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
107e0 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
107f0 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
10800 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
10810 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
10820 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
10830 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
10840 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
10850 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
10860 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
10870 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10880 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
10890 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
108a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
108b0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
108c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
108d0 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
108e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
108f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
10900 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
10910 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10920 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
10930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
10940 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
10950 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
10960 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
10970 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
10980 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
10990 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
109a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
109b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
109c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
109d0 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
109e0 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
109f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10a00 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
10a10 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
10a20 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
10a30 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
10a40 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
10a50 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
10a60 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
10a70 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
10a80 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
10a90 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
10aa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
10ab0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10ac0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
10ad0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
10ae0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
10af0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
10b00 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
10b10 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
10b20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
10b30 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
10b40 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10b50 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
10b60 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
10b70 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
10b80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10b90 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
10ba0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
10bb0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
10bc0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
10bd0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
10be0 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
10bf0 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
10c00 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
10c10 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
10c20 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
10c30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
10c40 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
10c50 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
10c60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
10c70 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
10c80 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
10c90 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ca0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
10cb0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
10cc0 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
10cd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10ce0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
10cf0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10d00 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
10d10 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
10d20 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
10d30 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
10d40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
10d50 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
10d60 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
10d70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
10d80 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
10d90 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
10da0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10db0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
10dc0 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
10dd0 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
10de0 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
10df0 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
10e00 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
10e10 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
10e20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
10e30 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
10e40 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
10e50 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
10e60 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
10e70 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
10e80 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
10e90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
10ea0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
10eb0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
10ec0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
10ed0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
10ee0 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
10ef0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
10f00 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10f10 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
10f20 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
10f30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10f40 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
10f50 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
10f60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
10f70 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
10f80 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
10f90 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
10fa0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
10fb0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
10fc0 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
10fd0 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
10fe0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
10ff0 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
11000 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
11010 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
11020 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
11030 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
11040 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
11050 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
11060 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
11070 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11080 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
11090 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
110a0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
110b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
110c0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
110d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
110e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
110f0 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
11100 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11110 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
11120 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
11130 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
11140 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
11150 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
11160 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
11170 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11180 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
11190 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
111a0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
111b0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
111c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
111d0 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
111e0 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
111f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
11200 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
11210 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
11220 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
11230 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
11240 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
11250 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
11260 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
11270 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
11280 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
11290 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
112a0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
112b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
112c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
112d0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
112e0 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
112f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
11300 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
11310 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
11320 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
11330 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
11340 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
11350 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
11360 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
11370 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
11380 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
11390 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
113a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
113b0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
113c0 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
113d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
113e0 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
113f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
11400 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
11410 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
11420 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
11430 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
11440 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11450 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
11460 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
11470 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11480 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
11490 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
114a0 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
114b0 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
114c0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
114d0 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
114e0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
114f0 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
11500 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
11510 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
11520 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
11530 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
11540 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
11550 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
11560 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
11570 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
11580 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
11590 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74  .** <b>The sqlit
115a0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
115b0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
115c0 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70  eadsafe. The app
115d0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
115e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   ensure that no 
115f0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11600 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
11610 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
11620 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
11630 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11640 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a  s running.</b>.*
11650 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11660 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11670 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ace.** may only 
11680 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
11690 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
116a0 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
116b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
116c0 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
116d0 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
116e0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
116f0 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
11700 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
11710 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
11720 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11730 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
11740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11750 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
11760 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
11770 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
11780 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
11790 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
117a0 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
117b0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
117c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
117d0 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
117e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
117f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
11800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
11810 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
11820 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11830 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
11840 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
11850 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
11860 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
11870 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
11880 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
11890 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
118a0 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
118b0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
118c0 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
118d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
118e0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
118f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
11900 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
11910 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
11920 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
11930 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
11940 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
11950 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
11960 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
11970 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
11980 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
11990 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
119a0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
119b0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
119c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
119d0 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
119e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
119f0 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
11a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11a10 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
11a20 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
11a30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11a40 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11a50 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
11a60 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
11a70 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
11a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11a90 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
11aa0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
11ab0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11ac0 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
11ad0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
11ae0 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
11af0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11b00 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
11b10 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
11b20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
11b30 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
11b40 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
11b50 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
11b60 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
11b70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
11b80 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
11b90 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
11ba0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
11bb0 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
11bc0 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
11bd0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
11be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
11bf0 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
11c00 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
11c10 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
11c20 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
11c30 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11c40 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
11c50 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
11c60 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
11c70 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
11c80 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
11c90 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
11ca0 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
11cb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
11cc0 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
11cd0 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
11ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11cf0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
11d00 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
11d10 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
11d20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
11d30 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
11d40 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
11d50 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
11d60 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
11d70 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
11d80 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
11d90 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
11da0 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
11db0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11dc0 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
11dd0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
11de0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
11df0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
11e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11e10 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
11e20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11e30 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
11e40 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11e50 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
11e60 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
11e70 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
11e80 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
11e90 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
11ea0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
11eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ec0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
11ed0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
11ee0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11ef0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
11f00 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
11f10 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11f30 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
11f40 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
11f50 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
11f60 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
11f70 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
11f80 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
11f90 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
11fa0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
11fb0 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
11fc0 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
11fd0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
11fe0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
11ff0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
12000 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
12010 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
12020 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
12030 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
12040 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
12050 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
12060 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
12070 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
12080 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
12090 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
120a0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
120b0 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
120c0 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
120d0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
120e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
120f0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
12100 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
12110 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
12120 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
12130 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
12140 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
12150 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
12160 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
12170 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
12180 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
12190 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
121a0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
121b0 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
121c0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
121d0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
121e0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
121f0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
12200 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
12210 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
12220 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
12230 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
12240 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
12250 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
12260 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
12270 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
12280 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
12290 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
122a0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
122b0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
122c0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
122d0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
122e0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
122f0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
12300 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
12310 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
12320 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
12330 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
12340 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
12350 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
12360 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
12370 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
12380 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
12390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
123a0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
123b0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
123c0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
123d0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
123e0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
123f0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
12400 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
12410 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
12420 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
12430 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
12440 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
12450 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
12460 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
12470 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12480 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
12490 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
124a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
124b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
124c0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
124d0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
124e0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
124f0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
12500 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
12510 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
12520 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
12530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
12540 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
12550 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
12560 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
12570 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
12580 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
12590 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
125a0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
125b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
125c0 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
125d0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
125e0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
125f0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
12600 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12610 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
12620 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
12630 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
12640 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
12650 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
12660 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
12670 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
12680 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
12690 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
126a0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
126b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
126c0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
126d0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
126e0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
126f0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
12700 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
12710 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
12720 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
12730 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
12740 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
12750 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
12760 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
12770 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
12780 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
12790 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
127a0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
127b0 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
127c0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
127d0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
127e0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
127f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
12800 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12810 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
12820 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
12830 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
12840 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
12850 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
12860 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
12870 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
12880 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
12890 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
128a0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
128b0 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
128c0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
128d0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
128e0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
128f0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
12900 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
12910 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
12920 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
12930 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
12940 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
12950 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
12960 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
12970 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
12980 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
12990 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
129a0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
129b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
129c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
129d0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
129e0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
129f0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
12a00 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12a10 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
12a20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
12a30 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
12a40 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
12a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
12a60 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
12a70 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
12a80 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
12a90 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12aa0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
12ab0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
12ac0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
12ad0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12ae0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
12af0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
12b00 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
12b10 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
12b20 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
12b30 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
12b40 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12b50 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
12b60 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12b70 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
12b80 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
12b90 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
12ba0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12bb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12bc0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
12bd0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
12be0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
12bf0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
12c00 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
12c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12c20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
12c30 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
12c40 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
12c50 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
12c60 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
12c70 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
12c80 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
12c90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12ca0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
12cb0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
12cc0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
12cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12ce0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
12cf0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
12d00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12d10 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
12d20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
12d30 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
12d40 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
12d50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
12d60 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
12d70 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
12d80 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
12d90 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
12da0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
12db0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
12dc0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
12dd0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
12de0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
12df0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
12e00 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
12e10 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
12e20 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
12e30 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
12e40 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
12e50 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
12e60 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
12e70 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
12e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12e90 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
12ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12eb0 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
12ec0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12ed0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12ee0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12ef0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12f00 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12f10 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
12f20 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
12f30 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
12f40 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
12f50 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
12f60 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
12f70 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
12f80 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
12f90 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
12fa0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
12fb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12fc0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12fd0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12fe0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12ff0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13000 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13010 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13020 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
13030 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13040 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
13050 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
13060 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
13070 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
13080 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
13090 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
130a0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
130b0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
130c0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
130d0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
130e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
130f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13100 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13110 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
13120 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
13130 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13140 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13150 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13160 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13170 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13180 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13190 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
131a0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
131b0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
131c0 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
131d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
131e0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
131f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13200 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
13210 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
13220 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
13230 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
13240 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
13250 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
13260 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13270 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
13280 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
13290 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
132a0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
132b0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
132c0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
132d0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
132e0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
132f0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
13300 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
13310 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13320 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
13330 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
13340 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13350 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13360 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13370 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13380 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13390 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
133a0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
133b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
133c0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
133d0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
133e0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
133f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13400 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
13410 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13420 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13440 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
13450 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13460 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13470 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13480 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
13490 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
134a0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
134b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
134c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
134d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
134e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
134f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13500 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
13510 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13520 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
13530 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
13540 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
13550 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
13560 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
13570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
13580 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
13590 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
135a0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
135b0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
135c0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
135d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
135e0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
135f0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
13600 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
13610 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
13620 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
13630 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
13640 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
13650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13660 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
13670 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
13680 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
13690 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
136a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
136b0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
136c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
136d0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
136e0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
136f0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
13700 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13710 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13730 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13740 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13750 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13760 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13770 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
13780 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
13790 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
137a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
137b0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
137c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
137d0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
137e0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
137f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
13800 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
13810 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
13820 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13830 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
13840 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13850 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13860 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13870 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
13880 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13890 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
138a0 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
138b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
138c0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
138d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
138e0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
138f0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13900 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
13910 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
13920 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13930 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
13940 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
13950 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
13960 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13970 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
13980 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
13990 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
139a0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
139b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
139c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
139d0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
139e0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
139f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13a00 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
13a10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13a20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13a30 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
13a40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13a50 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
13a60 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
13a70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
13a80 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13a90 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13aa0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
13ab0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13ac0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13ad0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13ae0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13b00 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
13b10 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
13b20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13b30 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
13b40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13b50 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
13b60 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
13b70 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
13b80 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
13b90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
13ba0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13bb0 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
13bc0 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
13bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13be0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
13bf0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
13c00 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
13c10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13c20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13c30 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
13c40 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
13c50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c70 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
13c80 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
13c90 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
13ca0 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
13cb0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
13cc0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
13cd0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
13ce0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
13cf0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13d00 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
13d10 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
13d20 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13d30 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
13d40 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
13d50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
13d60 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
13d70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
13d80 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
13d90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
13da0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
13db0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13dc0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
13dd0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13de0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
13df0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
13e00 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36  [sqlite3_status6
13e10 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  4()].**   </ul>)
13e20 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
13e30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13e40 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
13e50 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
13e60 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
13e70 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
13e80 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
13e90 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
13ea0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
13eb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13ec0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
13ed0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
13ee0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13ef0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13f00 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
13f10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13f20 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
13f30 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13f40 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
13f50 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
13f60 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
13f70 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
13f80 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63  e can use for sc
13f90 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e  ratch memory.  ^
13fa0 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  (There are three
13fb0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
13fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13fd0 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74  CRATCH:  A point
13fe0 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
13ff0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
14000 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
14010 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
14020 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
14030 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
14040 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
14050 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
14060 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
14070 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
14080 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
14090 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20  tions (N).)^.** 
140a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
140b0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
140c0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
140d0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
140e0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
140f0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
14100 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
14110 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f   will not use mo
14120 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
14130 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
14140 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69  thread..** ^SQLi
14150 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
14160 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20  quest a scratch 
14170 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
14180 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
14190 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
141a0 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e   page size..** ^
141b0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
141c0 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
141d0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
141e0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
141f0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
14200 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
14210 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
14220 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
14230 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
14240 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
14250 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70  memory needed.<p
14260 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61  >.** ^When the a
14270 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69  pplication provi
14280 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f  des any amount o
14290 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  f scratch memory
142a0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
142b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c  _CONFIG_SCRATCH,
142c0 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75   SQLite avoids u
142d0 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65  nnecessary large
142e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
142f0 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74  loc|heap allocat
14300 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63  ions]..** This c
14310 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20  an help [Robson 
14320 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65  proof|prevent me
14330 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14340 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f  failures] due to
14350 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e   heap.** fragmen
14360 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65  tation in low-me
14370 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79  mory embedded sy
14380 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  stems..** </dd>.
14390 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
143a0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
143b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
143c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
143d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
143f0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
14400 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72  pecifies a memor
14410 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53  y pool.** that S
14420 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
14430 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  r the database p
14440 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
14450 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a  he default page.
14460 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
14470 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
14480 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
14490 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d   option is a no-
144a0 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  op if an applica
144b0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
144c0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
144d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
144e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
144f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14500 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  HE2]..** ^There 
14510 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14520 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14530 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
14540 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
14550 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
14560 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68  emory (pMem), th
14570 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
14580 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28  age cache line (
14590 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
145a0 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20  number of cache 
145b0 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  lines (N)..** Th
145c0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
145d0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
145e0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
145f0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
14600 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
14610 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
14620 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
14630 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
14640 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
14650 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
14660 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
14670 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
14680 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
14690 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
146a0 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  d using [SQLITE_
146b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
146c0 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  RSZ]..** ^It is 
146d0 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
146e0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
146f0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
14700 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
14710 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
14720 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
14730 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65  e pMem.** argume
14740 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  nt must be eithe
14750 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
14760 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
14770 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14780 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
14790 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
147a0 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74  t sz*N bytes, ot
147b0 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65  herwise.** subse
147c0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
147d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
147e0 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f  ^When pMem is no
147f0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
14800 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73  ill strive to us
14810 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14820 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69  vided.** to sati
14830 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e  sfy page cache n
14840 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61  eeds, falling ba
14850 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ck to [sqlite3_m
14860 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61  alloc()] if.** a
14870 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14880 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20   is larger than 
14890 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61  sz bytes or if a
148a0 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62  ll of the pMem b
148b0 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61  uffer.** is exha
148c0 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d  usted..** ^If pM
148d0 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  em is NULL and N
148e0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
148f0 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  en each database
14900 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64   connection.** d
14910 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62  oes an initial b
14920 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ulk allocation f
14930 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
14940 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  mory.** from [sq
14950 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14960 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e  sufficient for N
14970 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20   cache lines if 
14980 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72  N is positive or
14990 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62  .** of -1024*N b
149a0 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67  ytes if N is neg
149b0 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64  ative, . ^If add
149c0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
149d0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
149e0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
149f0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14a00 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a  y the initial.**
14a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
14a20 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  n SQLite goes to
14a30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14a40 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66  ()] separately f
14a50 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74  or each.** addit
14a60 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65  ional cache line
14a70 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14a90 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
14aa0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
14ab0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14ad0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14ae0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14af0 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
14b00 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
14b10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
14b20 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14b30 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14b40 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
14b50 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
14b60 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14b70 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20  SCRATCH] and.** 
14b80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14b90 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54  AGECACHE]..** ^T
14ba0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14bb0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20  _HEAP option is 
14bc0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14bd0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14be0 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74  iled.** with eit
14bf0 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
14c00 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b  LE_MEMSYS3] or [
14c10 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
14c20 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72  MSYS5] and retur
14c30 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ns.** [SQLITE_ER
14c40 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20  ROR] if invoked 
14c50 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54  otherwise..** ^T
14c60 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14c70 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
14c80 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a  TE_CONFIG_HEAP:.
14c90 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  ** An 8-byte ali
14ca0 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
14cb0 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
14cc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
14cd0 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
14ce0 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
14cf0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14d00 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
14d10 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
14d20 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
14d30 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
14d40 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
14d50 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
14d60 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
14d70 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
14d80 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
14d90 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
14da0 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
14db0 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
14dc0 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
14dd0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
14de0 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
14df0 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
14e00 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61   NULL then the a
14e10 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
14e20 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
14e30 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
14e40 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
14e50 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
14e60 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
14e70 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
14e80 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
14e90 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
14ea0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
14eb0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
14ec0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
14ed0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
14ee0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
14ef0 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
14f00 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14f10 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
14f20 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
14f30 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
14f40 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
14f50 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
14f60 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
14f70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14f90 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
14fa0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
14fb0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14fd0 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
14fe0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14ff0 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a  nt which is a.**
15000 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15010 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
15020 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15030 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15040 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
15050 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65  t specifies alte
15060 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
15070 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
15080 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69   to be used.** i
15090 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65  n place the mute
150a0 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
150b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
150c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
150d0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
150e0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
150f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15100 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15110 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
15120 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15130 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
15140 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
15150 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15160 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
15170 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
15180 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
15190 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
151a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
151b0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
151c0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
151d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
151e0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
151f0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15200 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15210 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15220 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
15230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15240 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15250 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15260 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15270 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15280 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
15290 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
152a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
152b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
152c0 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  GETMUTEX option 
152d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
152e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
152f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15300 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15320 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15330 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
15340 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15350 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
15360 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
15370 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
15380 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
15390 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
153a0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
153b0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
153c0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
153d0 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
153e0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
153f0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
15400 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
15410 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
15420 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
15430 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
15440 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
15450 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15460 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
15470 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15480 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
15490 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
154a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
154b0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
154c0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
154d0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
154e0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
154f0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
15500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15510 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
15520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15530 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
15540 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
15550 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
15560 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
15570 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15580 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
15590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
155a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
155b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
155c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
155d0 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74  OKASIDE option t
155e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
155f0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
15600 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  e.** the default
15610 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69   size of lookasi
15620 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63  de memory on eac
15630 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
15640 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
15650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15660 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
15670 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
15680 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
15690 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
156a0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
156b0 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
156c0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
156d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
156e0 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  (SQLITE_CONFIG_L
156f0 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73  OOKASIDE.** sets
15700 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c   the <i>default<
15710 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
15720 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
15730 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15740 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f  DE].** option to
15750 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15760 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
15770 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
15780 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
15790 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
157a0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
157b0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
157c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
157d0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
157e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
157f0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
15800 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15810 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15820 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15830 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15840 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
15850 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
15860 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15870 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
15880 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
15890 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e  cifies.** the in
158a0 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73  terface to a cus
158b0 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
158c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
158d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .** ^SQLite make
158e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
158f0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15900 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
15910 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15930 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
15940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15950 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
15960 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
15970 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15980 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
15990 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
159a0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
159b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
159c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
159d0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
159e0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
159f0 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74  f.** the current
15a00 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
15a10 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
15a20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
15a30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15a40 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
15a50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15a60 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
15a70 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
15a80 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15a90 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
15aa0 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
15ab0 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
15ac0 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
15ad0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15ae0 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
15af0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
15b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
15b10 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
15b20 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
15b30 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
15b40 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
15b50 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
15b60 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
15b70 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
15b80 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
15b90 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
15ba0 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
15bb0 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
15bc0 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
15bd0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
15be0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
15bf0 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
15c00 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15c10 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
15c20 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
15c30 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
15c40 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
15c50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
15c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15c70 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
15c80 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
15c90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15ca0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15cb0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
15cc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
15cd0 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
15ce0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
15cf0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
15d00 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
15d10 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
15d20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
15d30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15d40 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
15d50 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
15d60 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
15d70 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
15d80 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
15d90 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
15da0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
15db0 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
15dc0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
15dd0 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
15de0 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
15df0 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
15e00 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
15e10 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
15e20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
15e30 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
15e40 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
15e50 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15e60 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
15e70 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
15e80 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
15e90 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
15ea0 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
15eb0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
15ec0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
15ed0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
15ee0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
15ef0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
15f00 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
15f10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15f20 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
15f30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
15f40 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  RI.** <dd>^(The 
15f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15f60 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  I option takes a
15f70 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15f80 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a   of type int..**
15f90 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
15fa0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
15fb0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
15fc0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
15fd0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a  meter is zero,.*
15fe0 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  * then URI handl
15ff0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
16000 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
16010 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16020 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62  globally.** enab
16030 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
16040 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  es passed to [sq
16050 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
16060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16070 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
16080 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
16090 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
160a0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
160b0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
160c0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
160d0 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
160e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
160f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
16100 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
16110 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
16120 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
16130 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
16140 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
16150 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
16160 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
16170 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16180 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
16190 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
161a0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
161b0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
161c0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
161d0 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
161e0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
161f0 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
16200 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
16210 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
16220 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
16230 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
16240 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
16250 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
16260 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
16270 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16280 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
16290 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
162a0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
162b0 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SCAN.** <dd>^The
162c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
162d0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
162e0 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  AN option takes 
162f0 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
16300 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69  .** argument whi
16310 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
16320 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  d as a boolean i
16330 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
16340 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e or disable.** 
16350 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
16360 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
16370 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
16380 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
16390 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65  timizer..** ^The
163a0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
163b0 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
163c0 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
163d0 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
163e0 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
163f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
16400 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
16410 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
16420 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
16430 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
16440 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
16450 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
16460 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
16470 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
16480 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
16490 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
164a0 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
164b0 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
164c0 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
164d0 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
164e0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
164f0 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
16500 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
16510 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
16520 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
16530 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
16540 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
16550 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
16560 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
16570 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
16580 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
16590 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
165a0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
165b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
165c0 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
165d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
165e0 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
165f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16600 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
16610 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
16620 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
16630 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
16640 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
16650 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
16660 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
16670 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
16680 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
16690 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
166a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
166b0 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
166c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
166d0 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
166e0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
166f0 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
16700 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
16710 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
16720 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
16730 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
16740 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
16750 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16760 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
16770 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
16780 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
16790 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
167a0 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
167b0 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
167c0 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
167d0 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
167e0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
167f0 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
16800 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
16810 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
16820 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
16830 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
16840 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
16850 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
16860 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
16870 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16880 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
16890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
168a0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
168b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
168c0 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
168d0 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
168e0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
168f0 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
16900 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
16910 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
16920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
16930 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
16940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
16950 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
16960 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
16970 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16980 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
16990 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
169a0 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
169b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
169c0 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
169d0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
169e0 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
169f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16a00 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
16a10 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
16a20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
16a30 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
16a40 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
16a50 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
16a60 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
16a70 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
16a80 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
16a90 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
16aa0 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
16ab0 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
16ac0 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
16ad0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
16ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16af0 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
16b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16b10 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
16b20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16b30 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
16b40 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
16b50 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
16b60 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
16b70 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
16b80 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
16b90 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
16ba0 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
16bb0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
16bc0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
16bd0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
16be0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
16bf0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
16c00 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
16c10 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
16c20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
16c30 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
16c40 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
16c50 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
16c60 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
16c70 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
16c80 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
16c90 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
16ca0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
16cb0 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c  mmap size.** wil
16cc0 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72  l be silently tr
16cd0 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73  uncated if neces
16ce0 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20  sary so that it 
16cf0 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20  does not exceed 
16d00 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  the.** compile-t
16d10 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
16d20 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
16d30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
16d40 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
16d50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
16d60 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
16d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
16d80 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
16d90 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
16da0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
16db0 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
16dc0 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
16dd0 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
16de0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16df0 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
16e00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
16e10 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
16e20 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16e30 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16e40 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73  APSIZE option is
16e50 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
16e60 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  if SQLite is.** 
16e70 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
16e80 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53  dows with the [S
16e90 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
16ea0 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
16eb0 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e  r macro.** defin
16ec0 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  ed. ^SQLITE_CONF
16ed0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16ee0 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
16ef0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16f00 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
16f10 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
16f20 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
16f30 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
16f40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16f50 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
16f60 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
16f70 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f80 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
16f90 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16fa0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
16fb0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16fc0 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16fd0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
16fe0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
16ff0 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
17000 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
17010 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
17020 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
17030 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
17040 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
17050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17060 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
17070 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61   amount of extra
17080 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
17090 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
170a0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
170b0 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
170c0 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
170d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
170e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
170f0 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c  FIG_PMASZ]].** <
17100 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17110 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _PMASZ.** <dd>^T
17120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17130 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _PMASZ option ta
17140 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17150 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17160 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69  is an unsigned i
17170 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20  nteger and sets 
17180 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41  the "Minimum PMA
17190 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d   Size" for the m
171a0 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20  ultithreaded.** 
171b0 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69  sorter to that i
171c0 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66  nteger.  The def
171d0 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41  ault minimum PMA
171e0 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20   Size is set by 
171f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
17200 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d  ORTER_PMASZ] com
17210 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17220 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61  .  New threads a
17230 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74  re launched.** t
17240 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74  o help with sort
17250 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e   operations when
17260 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73   multithreaded s
17270 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61  orting.** is ena
17280 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20  bled (using the 
17290 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d  [PRAGMA threads]
172a0 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68   command) and th
172b0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  e amount of cont
172c0 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72  ent.** to be sor
172d0 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20  ted exceeds the 
172e0 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20  page size times 
172f0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74  the minimum of t
17300 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61  he.** [PRAGMA ca
17310 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e  che_size] settin
17320 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65  g and this value
17330 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17340 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17350 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e  _SPILL]].** <dt>
17360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17370 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20  MTJRNL_SPILL.** 
17380 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17390 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
173a0 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b  SPILL option tak
173b0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
173c0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62  meter which.** b
173d0 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74  ecomes the [stat
173e0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73  ement journal] s
173f0 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72  pill-to-disk thr
17400 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74  eshold.  .** [St
17410 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
17420 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65  ] are held in me
17430 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72  mory until their
17440 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29   size (in bytes)
17450 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73  .** exceeds this
17460 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77   threshold, at w
17470 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20  hich point they 
17480 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64  are written to d
17490 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68  isk..** Or if th
174a0 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d  e threshold is -
174b0 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  1, statement jou
174c0 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73  rnals are always
174d0 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69   held.** exclusi
174e0 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a  vely in memory..
174f0 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74  ** Since many st
17500 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
17510 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61   never become la
17520 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65  rge, setting the
17530 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68   spill.** thresh
17540 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73  old to a value s
17550 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e  uch as 64KiB can
17560 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20   greatly reduce 
17570 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a  the amount of.**
17580 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f   I/O required to
17590 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65   support stateme
175a0 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  nt rollback..** 
175b0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
175c0 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69  e for this setti
175d0 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  ng is controlled
175e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
175f0 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  TE_STMTJRNL_SPIL
17600 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  L] compile-time 
17610 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e  option..** </dl>
17620 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
17640 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
17650 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17660 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
17670 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
17680 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
176a0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
176b0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
176c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
176d0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
176e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
176f0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
17700 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17710 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
17720 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
17730 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
17740 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17750 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
17760 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
17770 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
17780 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17790 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
177a0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
177b0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
177c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
177d0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
177e0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
177f0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
17800 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
17810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
17820 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
17830 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
17840 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17850 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
17860 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
17870 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
17880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17890 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
178a0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
178b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
178c0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
178d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
178e0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
178f0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
17900 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
17910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
17920 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
17930 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
17940 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17950 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
17960 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17980 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
17990 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
179c0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
179d0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
179e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
179f0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
17a00 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
17a10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17a20 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
17a30 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
17a40 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
17a50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a60 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17a70 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
17a80 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17a90 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
17aa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17ab0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17ac0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
17ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ae0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
17af0 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
17b00 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
17b10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17b20 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
17b30 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
17b40 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
17b50 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
17b60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17b70 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
17b80 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
17b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ba0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17bb0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
17bc0 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
17bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17be0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
17bf0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
17c00 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
17c10 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
17c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17c30 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
17c40 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
17c50 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  te */../*.** CAP
17c60 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
17c70 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
17c80 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
17c90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
17ca0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
17cb0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
17cc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17cd0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
17ce0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
17cf0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17d00 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
17d10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17d20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
17d30 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
17d40 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
17d50 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
17d60 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
17d70 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
17d80 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
17d90 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
17da0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
17db0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
17dc0 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
17dd0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
17de0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
17df0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
17e00 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
17e10 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
17e20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
17e30 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
17e40 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
17e50 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
17e60 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
17e70 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
17e80 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
17e90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17ea0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
17eb0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
17ec0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17ed0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
17ee0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17ef0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
17f00 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
17f10 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
17f20 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
17f30 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17f40 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
17f50 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
17f60 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
17f70 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
17f80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17f90 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
17fa0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
17fb0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
17fc0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
17fd0 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
17fe0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
17ff0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
18000 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18010 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
18020 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18030 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
18040 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
18050 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
18060 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
18070 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
18080 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
18090 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
180a0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
180b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
180c0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
180d0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
180e0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
180f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
18100 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
18110 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
18120 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
18130 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
18140 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
18150 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
18160 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
18170 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
18180 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
18190 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
181a0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
181b0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
181c0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
181d0 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
181e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
181f0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
18200 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
18210 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
18220 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
18230 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
18240 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
18250 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
18260 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
18270 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
18280 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
18290 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
182a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
182b0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
182c0 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
182d0 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
182e0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
182f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
18300 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
18310 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
18320 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
18330 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
18340 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
18350 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
18360 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
18370 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
18380 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
18390 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
183a0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
183b0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
183c0 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
183d0 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
183e0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
183f0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
18400 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
18410 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
18420 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18430 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18440 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
18450 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18460 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18470 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18480 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
18490 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
184a0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
184b0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
184c0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
184d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
184e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
184f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18500 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18510 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
18520 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
18530 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
18540 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
18550 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18560 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
18570 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
18580 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18590 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
185a0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
185b0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
185c0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
185d0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
185e0 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
185f0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
18600 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
18610 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
18620 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
18630 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18640 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
18650 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
18660 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
18670 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18680 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18690 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
186a0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
186b0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
186c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
186d0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
186e0 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
186f0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18700 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
18710 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18720 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18730 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18740 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18750 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18760 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
18770 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
18780 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
18790 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
187a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
187b0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
187c0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
187d0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
187e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
187f0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18800 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18810 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18820 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
18830 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
18840 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18850 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18860 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18870 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18880 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18890 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
188a0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
188b0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
188c0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
188d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
188e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
188f0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
18900 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
18910 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18920 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18930 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f   disable the two
18940 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72  -argument.** ver
18950 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73  sion of the [fts
18960 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66  3_tokenizer()] f
18970 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73  unction which is
18980 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
18990 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74  [FTS3] full-text
189a0 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65   search engine e
189b0 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65  xtension..** The
189c0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
189d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
189e0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
189f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
18a00 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
18a10 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
18a20 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
18a30 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ) or.** positive
18a40 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f   to enable fts3_
18a50 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e  tokenizer() or n
18a60 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
18a70 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
18a80 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18a90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18aa0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18ab0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18ac0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18ad0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18ae0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18af0 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  r fts3_tokenizer
18b00 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
18b10 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
18b20 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18b30 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18b40 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18b50 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18b60 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18b70 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
18b80 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18b90 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
18ba0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18bb0 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
18bc0 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a  EXTENSION</dt>.*
18bd0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18be0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18bf0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18c00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
18c10 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
18c20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64  ** interface ind
18c30 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68  ependently of th
18c40 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
18c50 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  n()] SQL functio
18c60 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  n..** The [sqlit
18c70 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
18c80 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20  xtension()] API 
18c90 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
18ca0 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20  les both the.** 
18cb0 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c  C-API [sqlite3_l
18cc0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18cd0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18ce0 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65  ction [load_exte
18cf0 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65  nsion()]..** The
18d00 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
18d10 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
18d20 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  ments..** When t
18d30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18d40 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66  t to this interf
18d50 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f  ace is 1, then o
18d60 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73  nly the C-API is
18d70 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20  .** enabled and 
18d80 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18d90 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65   remains disable
18da0 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  d.  If the first
18db0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18dc0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18dd0 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74  s 0, then both t
18de0 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65  he C-API and the
18df0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72   SQL function ar
18e00 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49  e disabled..** I
18e10 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
18e20 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e  ment is -1, then
18e30 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20   no changes are 
18e40 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66  made to state of
18e50 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43   either the.** C
18e60 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20  -API or the SQL 
18e70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18e80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18e90 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18ea0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18eb0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18ec0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18ed0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18ee0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18ef0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
18f00 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61  rface.** is disa
18f10 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20  bled or enabled 
18f20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18f30 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18f40 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a   parameter may.*
18f50 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * be a NULL poin
18f60 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ter, in which ca
18f70 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18f80 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18f90 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64  ed back..** </dd
18fa0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18fb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
18fc0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
18fd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18fe0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
18ff0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
19000 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
19010 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
19020 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
19030 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
19040 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
19050 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
19060 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
19070 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
19080 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
19090 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
190a0 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
190b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
190c0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
190d0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
190e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
190f0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
19100 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
19110 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
19120 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
19130 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
19140 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
19150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19160 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
19170 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19180 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
19190 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c  O_CKPT_ON_CLOSE<
191a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75  /dt>.** <dd> Usu
191b0 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74  ally, when a dat
191c0 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64  abase in wal mod
191d0 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64  e is closed or d
191e0 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a  etached from a .
191f0 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
19200 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b  le, SQLite check
19210 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d  s if this will m
19220 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61  ean that there a
19230 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f  re now no .** co
19240 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c  nnections at all
19250 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
19260 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66  . If so, it perf
19270 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e  orms a checkpoin
19280 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  t .** operation 
19290 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74  before closing t
192a0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54  he connection. T
192b0 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  his option may b
192c0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65  e used to.** ove
192d0 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76  rride this behav
192e0 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20  iour. The first 
192f0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
19300 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69   to this operati
19310 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  on.** is an inte
19320 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74  ger - non-zero t
19330 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70  o disable checkp
19340 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20  oints-on-close, 
19350 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20  or zero (the.** 
19360 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62  default) to enab
19370 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63  le them. The sec
19380 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
193a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f   integer.** into
193b0 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65   which is writte
193c0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
193d0 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65  cate whether che
193e0 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73  ckpoints-on-clos
193f0 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64  e.** have been d
19400 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74  isabled - 0 if t
19410 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61  hey are not disa
19420 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20  bled, 1 if they 
19430 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  are..** </dd>.**
19440 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19450 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51  BCONFIG_ENABLE_Q
19460 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PSG</dt>.** <dd>
19470 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43  ^(The SQLITE_DBC
19480 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
19490 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74  G option activat
194a0 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65  es or deactivate
194b0 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20  s.** the [query 
194c0 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74  planner stabilit
194d0 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50  y guarantee] (QP
194e0 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51  SG).  When the Q
194f0 50 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a  PSG is active,.*
19500 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71  * a single SQL q
19510 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77  uery statement w
19520 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74  ill always use t
19530 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
19540 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  m regardless.** 
19550 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f  of values of [bo
19560 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e  und parameters].
19570 29 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61  )^ The QPSG disa
19580 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20  bles some query 
19590 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a  optimizations.**
195a0 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68   that look at th
195b0 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e  e values of boun
195c0 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68  d parameters, wh
195d0 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d  ich can make som
195e0 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f  e queries.** slo
195f0 77 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50  wer.  But the QP
19600 53 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e  SG has the advan
19610 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65  tage of more pre
19620 64 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f  dictable behavio
19630 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20  r.  With.** the 
19640 51 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c  QPSG active, SQL
19650 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
19660 75 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65  use the same que
19670 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66  ry plan in the f
19680 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75  ield as.** was u
19690 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
196a0 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a  ng in the lab..*
196b0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  * </dd>.**.** </
196c0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
196d0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
196e0 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20  AINDBNAME       
196f0 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e       1000 /* con
19700 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66  st char* */.#def
19710 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19720 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
19730 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
19740 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
19750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19760 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19770 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
19780 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
19790 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
197a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
197b0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
197c0 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
197d0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
197e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
197f0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
19800 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
19810 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19820 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19830 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
19840 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
19850 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19860 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19870 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
19880 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a  OSE      1006 /*
19890 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
198a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
198b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
198c0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20             1007 
198d0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
198e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
198f0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
19900 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
19910 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
19920 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19930 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
19940 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
19950 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
19960 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
19970 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
19980 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
19990 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
199a0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
199b0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
199c0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
199d0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
199e0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
199f0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
19a00 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
19a10 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
19a20 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
19a30 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
19a40 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
19a50 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
19a60 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19a70 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
19a80 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
19a90 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
19aa0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19ab0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
19ac0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
19ad0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
19ae0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
19af0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
19b00 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
19b10 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
19b20 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
19b30 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
19b40 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
19b50 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
19b60 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
19b70 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
19b80 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
19b90 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
19ba0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
19bb0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
19bc0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
19bd0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
19be0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
19bf0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
19c00 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
19c10 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
19c20 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19c30 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
19c40 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
19c50 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
19c60 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
19c70 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
19c80 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
19c90 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
19ca0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
19cb0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
19cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
19cd0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
19ce0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19cf0 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
19d00 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
19d10 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
19d20 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
19d30 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
19d40 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
19d50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19d60 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
19d70 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19d80 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
19d90 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
19da0 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
19db0 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
19dc0 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
19dd0 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
19de0 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
19df0 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
19e00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19e10 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
19e20 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
19e30 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
19e40 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
19e50 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
19e60 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
19e70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
19e80 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
19e90 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19ea0 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
19eb0 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
19ec0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
19ed0 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
19ee0 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
19ef0 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
19f00 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
19f10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
19f20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
19f30 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
19f40 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
19f50 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
19f60 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
19f70 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
19f80 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
19f90 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
19fa0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19fb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
19fc0 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
19fd0 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
19fe0 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
19ff0 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
1a000 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
1a010 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
1a020 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
1a030 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1a040 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a050 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1a060 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1a070 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1a080 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1a090 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1a0a0 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1a0b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a0c0 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1a0d0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1a0e0 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1a0f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1a100 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1a110 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1a120 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1a130 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1a140 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1a150 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1a160 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1a170 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1a180 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1a190 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1a1a0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1a1b0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1a1c0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1a1d0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1a1e0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1a1f0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1a200 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1a210 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1a220 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1a230 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1a240 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1a250 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1a260 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1a270 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1a280 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1a290 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1a2a0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1a2b0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1a2c0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1a2d0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1a2e0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1a2f0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1a300 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1a310 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1a320 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1a330 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1a340 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1a350 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1a360 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1a370 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1a380 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1a390 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1a3a0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1a3b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1a3c0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1a3d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1a3e0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1a3f0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1a400 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1a410 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1a420 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1a430 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1a440 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1a450 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1a460 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1a470 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1a480 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1a490 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1a4a0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1a4b0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1a4c0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1a4d0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1a4e0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1a4f0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1a500 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1a510 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1a520 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a530 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1a540 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1a550 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1a560 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1a570 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1a580 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a590 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1a5a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a5b0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1a5c0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1a5d0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1a5e0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1a5f0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1a600 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1a610 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1a620 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a630 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1a640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a650 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1a660 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1a670 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1a680 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1a690 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1a6a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1a6b0 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1a6c0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1a6d0 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1a6e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a6f0 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1a700 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a710 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1a720 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1a730 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1a740 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1a750 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1a760 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a770 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1a780 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1a790 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1a7a0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1a7b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a7c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a7d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a7e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a7f0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a800 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1a810 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a820 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1a830 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1a840 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a850 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1a860 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1a870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a880 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1a890 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1a8a0 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1a8b0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1a8c0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1a8d0 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1a8e0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1a8f0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1a900 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1a910 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1a920 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1a930 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a940 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a950 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1a960 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1a970 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1a980 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1a990 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1a9a0 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1a9b0 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1a9c0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a9d0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1a9e0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a9f0 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1aa00 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1aa10 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1aa20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1aa30 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1aa40 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1aa50 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1aa60 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1aa70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1aa80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1aa90 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1aaa0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1aab0 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1aac0 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1aad0 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1aae0 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1aaf0 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1ab00 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1ab10 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1ab20 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1ab30 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1ab40 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1ab50 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1ab60 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1ab70 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1ab80 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1ab90 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1aba0 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1abb0 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1abc0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1abd0 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1abe0 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1abf0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1ac00 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1ac10 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1ac20 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1ac30 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1ac40 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1ac50 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1ac60 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1ac70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1ac80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1ac90 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1aca0 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1acb0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1acc0 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1acd0 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1ace0 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1acf0 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1ad00 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1ad10 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1ad20 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1ad30 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1ad40 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1ad50 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1ad60 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1ad70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ad80 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1ad90 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1ada0 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1adb0 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1adc0 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1add0 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1ade0 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1adf0 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1ae00 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1ae10 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ae20 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1ae30 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1ae40 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1ae50 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1ae60 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1ae70 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1ae80 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1ae90 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1aea0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1aeb0 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1aec0 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1aed0 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1aee0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1aef0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1af00 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1af10 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1af20 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1af30 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1af40 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1af50 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1af60 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1af70 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1af80 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1af90 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1afa0 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1afb0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1afc0 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1afd0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1afe0 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1aff0 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1b000 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1b010 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1b020 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1b030 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1b040 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1b050 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b060 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b070 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b080 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b090 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1b0a0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1b0b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1b0c0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1b0d0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1b0e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1b0f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1b100 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1b110 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1b120 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1b130 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1b140 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1b150 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1b160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b170 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1b180 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b190 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1b1a0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1b1b0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1b1c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1b1d0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b1e0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1b1f0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1b200 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1b210 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1b220 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1b230 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1b240 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1b250 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1b260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b270 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1b280 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1b290 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1b2a0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1b2b0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1b2c0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1b2d0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1b2e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1b2f0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1b300 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b310 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1b320 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1b330 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1b340 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1b350 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1b360 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1b370 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1b380 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1b390 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1b3a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1b3b0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1b3c0 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1b3d0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1b3e0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1b3f0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1b400 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1b410 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
1b420 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1b430 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1b440 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1b450 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1b460 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1b470 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
1b480 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1b490 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1b4a0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1b4b0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1b4c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1b4d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1b4e0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
1b4f0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
1b500 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1b510 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1b520 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
1b530 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1b540 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
1b550 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b560 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1b570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b580 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1b590 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1b5a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b5b0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b5c0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1b5d0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1b5e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1b5f0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1b600 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1b610 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1b620 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1b630 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1b640 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1b650 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1b660 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1b670 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1b680 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1b690 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1b6a0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1b6b0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1b6c0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1b6d0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1b6e0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1b6f0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1b700 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1b710 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1b720 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1b730 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1b740 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1b750 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1b760 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1b770 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b780 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1b790 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1b7a0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1b7b0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1b7c0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1b7d0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1b7e0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1b7f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1b800 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1b810 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1b820 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1b830 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1b840 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1b850 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1b860 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1b870 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1b880 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1b890 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1b8a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1b8b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1b8c0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1b8d0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1b8e0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1b8f0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1b900 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1b910 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1b920 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b930 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1b940 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1b950 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1b960 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1b970 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1b980 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1b990 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1b9a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b9b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1b9c0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1b9d0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1b9e0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1b9f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1ba00 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1ba10 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1ba20 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1ba30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1ba40 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1ba50 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1ba60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ba70 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1ba80 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1ba90 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1baa0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1bab0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1bac0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1bad0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1bae0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1baf0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1bb00 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1bb10 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1bb20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1bb30 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1bb40 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1bb50 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1bb60 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1bb70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1bb80 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1bb90 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1bba0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1bbb0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1bbc0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1bbd0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1bbe0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1bbf0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1bc00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1bc10 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1bc20 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1bc30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1bc40 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1bc50 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1bc60 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1bc70 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1bc80 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1bc90 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1bca0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1bcb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bcc0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1bcd0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1bce0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1bcf0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1bd00 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1bd10 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1bd20 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1bd30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bd40 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1bd50 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1bd60 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1bd70 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1bd80 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1bd90 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1bda0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bdb0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1bdc0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1bdd0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1bde0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1bdf0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1be00 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1be10 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1be20 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1be30 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1be40 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1be50 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1be60 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1be70 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1be80 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1be90 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1bea0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1beb0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1bec0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1bed0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1bee0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1bef0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1bf00 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1bf10 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1bf20 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1bf30 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1bf40 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1bf50 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1bf60 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1bf70 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1bf80 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1bf90 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1bfa0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1bfb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1bfc0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bfd0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1bfe0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1bff0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1c000 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1c010 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1c020 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1c030 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1c040 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1c050 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1c060 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1c070 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1c080 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1c090 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1c0a0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1c0b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1c0c0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1c0d0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1c0e0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1c0f0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1c100 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c110 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1c120 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1c130 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1c140 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1c150 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1c160 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1c170 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1c180 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1c190 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1c1a0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c1b0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1c1c0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1c1d0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1c1e0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1c1f0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1c200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1c210 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1c220 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1c230 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c240 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1c250 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1c260 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1c270 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1c280 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c290 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1c2a0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1c2b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1c2c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1c2d0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1c2e0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
1c2f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c300 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1c310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c320 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1c330 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1c340 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1c350 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1c360 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1c370 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1c380 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1c390 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c3a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1c3b0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1c3c0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1c3d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c3e0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1c3f0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1c400 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1c410 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1c420 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1c430 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1c440 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1c450 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1c460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c470 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1c480 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1c490 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1c4a0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1c4b0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1c4c0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1c4d0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1c4e0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1c4f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1c500 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1c510 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1c520 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1c530 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1c540 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1c550 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1c560 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1c570 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1c580 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1c590 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1c5a0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1c5b0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1c5c0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1c5d0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1c5e0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1c5f0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1c600 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1c610 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1c620 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1c630 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1c640 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1c650 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1c660 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c670 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1c680 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1c690 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1c6a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1c6b0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1c6c0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1c6d0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1c6e0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1c6f0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1c700 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1c710 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1c720 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1c730 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1c740 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1c750 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1c760 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1c770 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1c780 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1c790 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1c7a0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1c7b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1c7c0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1c7d0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1c7e0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1c7f0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1c800 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1c810 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1c820 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1c830 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1c840 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1c850 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1c860 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1c870 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1c880 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1c890 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1c8a0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1c8b0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1c8c0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1c8d0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1c8e0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1c8f0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1c900 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1c910 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1c920 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1c930 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1c940 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1c950 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1c960 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1c970 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1c980 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1c990 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1c9a0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1c9b0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c9c0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1c9d0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1c9e0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1c9f0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1ca00 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1ca10 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1ca20 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1ca30 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1ca40 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1ca50 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1ca60 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1ca70 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1ca80 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1ca90 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1caa0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1cab0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1cac0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1cad0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1cae0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1caf0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1cb00 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1cb10 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1cb20 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1cb30 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1cb40 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1cb50 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1cb60 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1cb70 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1cb80 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1cb90 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1cba0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1cbb0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1cbc0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1cbd0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1cbe0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1cbf0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1cc00 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1cc10 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1cc20 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1cc30 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1cc40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1cc50 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1cc60 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1cc70 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1cc80 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1cc90 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1cca0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1ccb0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1ccc0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1ccd0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1cce0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1ccf0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1cd00 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1cd10 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1cd20 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1cd30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1cd40 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1cd50 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1cd60 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1cd70 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1cd80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cd90 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1cda0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1cdb0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1cdc0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1cdd0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1cde0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1cdf0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1ce00 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1ce10 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1ce20 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1ce30 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1ce40 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1ce50 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1ce60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ce70 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1ce80 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1ce90 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1cea0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ceb0 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29  (sqlite3*,int(*)
1cec0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64  (void*,int),void
1ced0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cee0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1cef0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1cf00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1cf10 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1cf20 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1cf30 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1cf40 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1cf50 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1cf60 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1cf70 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1cf80 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1cf90 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1cfa0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1cfb0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1cfc0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1cfd0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1cfe0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1cff0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1d000 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1d010 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1d020 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1d030 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1d040 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1d050 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1d060 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1d070 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1d080 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1d090 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1d0a0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1d0b0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1d0c0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1d0d0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1d0e0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1d0f0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1d100 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1d110 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1d120 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1d130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d140 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1d150 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1d160 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d170 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1d180 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1d190 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d1a0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d1b0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d1c0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d1d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d1e0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1d1f0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1d200 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d210 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1d220 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1d230 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1d240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d250 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1d260 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1d270 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1d280 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1d290 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1d2a0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1d2b0 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1d2c0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1d2d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1d2e0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1d2f0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1d300 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1d310 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1d320 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1d330 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1d340 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1d350 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1d360 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d370 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1d380 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1d390 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1d3a0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1d3b0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1d3c0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1d3d0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1d3e0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1d3f0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1d400 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1d410 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1d420 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1d430 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1d440 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1d450 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1d460 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1d470 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1d480 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1d490 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1d4a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d4b0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1d4c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1d4d0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1d4e0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1d4f0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1d500 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1d510 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1d520 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1d530 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1d540 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1d550 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1d560 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1d570 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1d580 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1d590 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1d5a0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1d5b0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1d5c0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1d5d0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1d5e0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1d5f0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1d600 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1d610 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1d620 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1d630 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1d640 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1d650 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1d660 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1d670 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1d680 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1d690 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1d6a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1d6b0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1d6c0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1d6d0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1d6e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1d6f0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1d700 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1d710 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1d720 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1d730 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1d740 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1d750 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1d760 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1d770 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1d780 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1d790 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1d7a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d7b0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1d7c0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1d7d0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1d7e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1d7f0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1d800 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1d810 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1d820 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1d830 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1d840 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d850 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1d860 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1d870 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1d880 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1d890 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1d8a0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1d8b0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1d8c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1d8d0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1d8e0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1d8f0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1d900 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1d910 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1d920 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d930 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1d940 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1d950 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1d960 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d970 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1d980 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d990 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1d9a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d9b0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1d9c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d9d0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1d9e0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1d9f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1da00 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1da10 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1da20 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1da30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1da40 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1da50 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1da60 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1da70 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1da80 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1da90 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1daa0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1dab0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1dac0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1dad0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1dae0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1daf0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1db00 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1db10 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1db20 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1db30 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1db40 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1db50 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1db60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1db70 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1db80 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1db90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1dba0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1dbb0 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1dbc0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1dbd0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1dbe0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1dbf0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1dc00 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1dc10 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1dc20 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1dc30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1dc40 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1dc50 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1dc60 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1dc70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1dc80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1dc90 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1dca0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1dcb0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1dcc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1dcd0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1dce0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1dcf0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1dd00 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1dd10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1dd20 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1dd30 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1dd40 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1dd50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1dd60 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1dd70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1dd80 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1dd90 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1dda0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1ddb0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1ddc0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1ddd0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1dde0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1ddf0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1de00 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1de10 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1de20 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1de30 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1de40 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1de50 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1de60 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1de70 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1de80 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1de90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1dea0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1deb0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1dec0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1ded0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1dee0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1def0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1df00 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1df10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1df20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1df30 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1df40 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1df50 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1df60 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1df70 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1df80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1df90 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1dfa0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1dfb0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1dfc0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1dfd0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1dfe0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1dff0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1e000 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1e010 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1e020 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1e030 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1e040 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1e050 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1e060 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1e070 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1e080 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1e090 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1e0a0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1e0b0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1e0c0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1e0d0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1e0e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1e0f0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1e100 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1e110 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1e120 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1e130 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1e140 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1e150 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1e160 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1e170 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1e180 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1e190 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1e1a0 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1e1b0 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1e1c0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1e1d0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1e1e0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1e1f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1e200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e210 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1e220 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1e230 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1e240 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1e250 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1e260 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1e270 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1e280 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1e290 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1e2a0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1e2b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1e2c0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1e2d0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1e2e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e2f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1e300 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1e310 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1e320 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1e330 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1e340 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1e350 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1e360 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1e370 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1e380 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1e390 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1e3a0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1e3b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1e3c0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1e3d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1e3e0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1e3f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1e400 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1e410 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1e420 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1e430 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1e440 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1e450 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1e460 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1e470 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1e480 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1e490 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1e4a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1e4b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1e4c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1e4d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1e4e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1e4f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1e500 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1e510 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1e520 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1e530 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1e540 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1e550 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1e560 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1e570 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1e580 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1e590 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1e5a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1e5b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1e5c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1e5d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1e5e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1e5f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1e600 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1e610 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1e620 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1e630 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1e640 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1e650 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1e660 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1e670 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1e680 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1e690 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1e6a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1e6b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1e6c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1e6d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1e6e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1e6f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1e700 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1e710 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1e720 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1e730 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1e740 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1e750 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1e760 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1e770 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1e780 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e790 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1e7a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1e7b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1e7c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e7d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1e7e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1e7f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1e800 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1e810 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1e820 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1e830 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1e840 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1e850 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1e860 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1e870 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1e880 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1e890 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1e8a0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1e8b0 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1e8c0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1e8d0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1e8e0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1e8f0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1e900 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1e910 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1e920 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1e930 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1e940 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1e950 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1e960 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1e970 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1e980 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1e990 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1e9a0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1e9b0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1e9c0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1e9d0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1e9e0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1e9f0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1ea00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1ea10 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1ea20 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1ea30 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1ea40 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1ea50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ea60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1ea70 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1ea80 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1ea90 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1eaa0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1eab0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1eac0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1ead0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1eae0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1eaf0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1eb00 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1eb10 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1eb20 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1eb30 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1eb40 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1eb50 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1eb60 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1eb70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1eb80 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1eb90 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1eba0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1ebb0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1ebc0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1ebd0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1ebe0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1ebf0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1ec00 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1ec10 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1ec20 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1ec30 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1ec40 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1ec50 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1ec60 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1ec70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1ec80 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1ec90 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1eca0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1ecb0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1ecc0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1ecd0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1ece0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ecf0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ed00 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ed10 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ed20 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ed30 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ed40 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1ed50 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1ed60 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1ed70 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1ed80 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1ed90 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1eda0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1edb0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1edc0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1edd0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1ede0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1edf0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1ee00 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1ee10 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1ee20 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1ee30 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1ee40 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1ee50 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1ee60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1ee70 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1ee80 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1ee90 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1eea0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1eeb0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1eec0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1eed0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1eee0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1eef0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1ef00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ef10 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1ef20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1ef30 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1ef40 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1ef50 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1ef60 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1ef70 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1ef80 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1ef90 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1efa0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1efb0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1efc0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1efd0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1efe0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1eff0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1f000 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1f010 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1f020 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1f030 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1f040 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1f050 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1f060 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1f070 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1f080 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1f090 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1f0a0 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1f0b0 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1f0c0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1f0d0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1f0e0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1f0f0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1f100 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1f110 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1f120 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1f130 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1f140 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1f150 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1f160 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1f170 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1f180 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1f190 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1f1a0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1f1b0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1f1c0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1f1d0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1f1e0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1f1f0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1f200 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1f210 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1f220 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1f230 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1f240 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1f250 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1f260 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1f270 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1f280 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f290 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f2a0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1f2b0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f2c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f2d0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1f2e0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f2f0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f300 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f320 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f330 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f340 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f350 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f360 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f370 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f380 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f3a0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1f3b0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1f3c0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1f3d0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1f3e0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1f3f0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f400 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1f410 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1f420 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1f430 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1f440 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1f450 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f460 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1f470 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1f480 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1f490 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1f4a0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1f4b0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1f4c0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1f4d0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f4e0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1f4f0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1f500 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1f510 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1f520 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f530 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1f540 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1f550 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f560 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1f570 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1f580 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1f590 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1f5a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1f5b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f5c0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1f5d0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1f5e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1f5f0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f600 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1f610 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1f620 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1f630 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1f640 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1f650 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1f660 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1f670 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1f680 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f690 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1f6a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f6b0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1f6c0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1f6d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1f6e0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1f6f0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1f700 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1f710 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1f720 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1f730 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1f740 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1f750 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f760 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1f770 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1f780 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1f790 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1f7a0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1f7b0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1f7c0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1f7d0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1f7e0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1f7f0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1f800 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f810 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1f820 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1f830 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1f840 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1f850 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1f860 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1f870 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1f880 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1f890 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1f8a0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1f8b0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1f8c0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f8d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1f8e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f8f0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1f900 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1f910 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1f920 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1f930 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1f940 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1f950 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1f960 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f970 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f980 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1f990 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1f9a0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1f9b0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1f9c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f9d0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1f9e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1f9f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fa00 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1fa10 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1fa20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1fa30 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1fa40 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1fa50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1fa60 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1fa70 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1fa80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1fa90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1faa0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1fab0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1fac0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1fad0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1fae0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1faf0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1fb00 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1fb10 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1fb20 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1fb30 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1fb40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1fb50 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1fb60 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1fb70 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1fb80 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1fb90 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1fba0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fbb0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1fbc0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1fbd0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1fbe0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1fbf0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1fc00 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1fc10 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1fc20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1fc30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1fc40 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1fc50 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1fc60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1fc70 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1fc80 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1fc90 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1fca0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1fcb0 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1fcc0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1fcd0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1fce0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1fcf0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1fd00 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1fd10 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1fd20 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1fd30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fd40 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1fd50 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1fd60 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1fd70 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1fd80 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1fd90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1fda0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1fdb0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fdc0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1fdd0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1fde0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1fdf0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1fe00 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1fe10 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1fe20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1fe30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1fe40 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1fe50 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1fe60 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1fe70 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1fe80 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1fe90 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1fea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1feb0 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1fec0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1fed0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1fee0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1fef0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1ff00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ff10 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1ff20 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1ff30 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1ff40 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1ff50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1ff60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1ff70 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1ff80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1ff90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ffa0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1ffb0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1ffc0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1ffd0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1ffe0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1fff0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
20000 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
20010 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
20020 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
20030 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
20040 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
20050 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
20060 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
20070 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
20080 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
20090 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
200a0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
200b0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
200c0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
200d0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
200e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
200f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
20100 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
20110 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
20120 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
20130 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
20140 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
20150 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
20160 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
20170 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
20180 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
20190 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
201a0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
201b0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
201c0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
201d0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
201e0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
201f0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
20200 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
20210 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
20220 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
20230 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
20240 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
20250 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20260 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
20270 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
20280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
20290 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
202a0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
202b0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
202c0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
202d0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
202e0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
202f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
20300 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
20310 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
20320 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
20330 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
20340 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
20350 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
20360 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
20370 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
20380 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
20390 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
203a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
203b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
203c0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
203d0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
203e0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
203f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
20400 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
20410 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
20420 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
20430 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
20440 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
20450 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
20460 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
20470 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
20480 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
20490 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
204a0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
204b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
204c0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
204d0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
204e0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
204f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
20500 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
20510 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
20520 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
20530 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
20540 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
20550 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
20560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20570 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
20580 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
20590 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
205a0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
205b0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
205c0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
205d0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
205e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
205f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20600 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20610 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
20620 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
20630 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
20640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20650 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
20660 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
20670 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20680 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20690 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
206a0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
206b0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
206c0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
206d0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
206e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
206f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20700 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
20710 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
20720 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
20730 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20740 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
20750 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20760 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
20770 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
20780 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
20790 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
207a0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
207b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
207c0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
207d0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
207e0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
207f0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
20800 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20810 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
20820 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
20830 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20840 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
20850 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
20860 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
20870 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20880 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
20890 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
208a0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
208b0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
208c0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
208d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
208e0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
208f0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
20900 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
20910 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20920 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
20930 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20940 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
20950 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20960 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
20970 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20980 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
20990 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
209a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
209b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
209c0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
209d0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
209e0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
209f0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
20a00 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
20a10 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
20a20 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
20a30 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
20a40 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
20a50 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20a60 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
20a70 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
20a80 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
20a90 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
20aa0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20ab0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20ac0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20ad0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20ae0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20af0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
20b00 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
20b10 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
20b20 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
20b30 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
20b40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
20b50 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20b60 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
20b70 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
20b80 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
20b90 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
20ba0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
20bb0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20bc0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20bd0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20be0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
20bf0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
20c00 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
20c10 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
20c20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20c30 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
20c40 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
20c50 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
20c60 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
20c70 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
20c80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
20c90 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
20ca0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
20cb0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20cc0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20cd0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20ce0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
20cf0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
20d00 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
20d10 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
20d20 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
20d30 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
20d40 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
20d50 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20d60 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
20d70 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
20d80 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
20d90 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
20da0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
20db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
20dc0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20dd0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
20de0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
20df0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
20e00 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
20e10 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
20e20 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
20e30 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
20e40 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
20e50 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f  KEYWORDS: {autho
20e60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a  rizer callback}.
20e70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20e80 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20e90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20ea0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20eb0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20ed0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20ee0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20ef0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20f00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20f10 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
20f20 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
20f30 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
20f40 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
20f50 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20f60 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
20f70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20f80 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20f90 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
20fa0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
20fb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20fc0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e  e16_v2()],.** an
20fd0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20fe0 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74  re16_v3()].  ^At
20ff0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
21000 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
21010 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
21020 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
21030 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
21040 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
21050 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
21060 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21070 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
21080 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
21090 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
210a0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
210b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
210c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
210d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
210e0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
210f0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
21100 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
21110 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
21120 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
21130 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21140 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
21150 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
21160 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
21170 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
21180 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
21190 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
211a0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
211b0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
211c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
211d0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
211e0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
211f0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
21200 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
21210 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
21220 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
21230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21240 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
21250 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
21260 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
21270 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
21280 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
21290 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
212a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
212b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
212c0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
212d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
212e0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
212f0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
21300 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21310 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
21320 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
21330 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
21340 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
21350 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
21360 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
21370 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
21380 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
21390 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
213a0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
213b0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
213c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
213d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
213e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
213f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
21400 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
21410 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
21420 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
21430 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
21440 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21450 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
21460 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21470 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
21480 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
21490 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
214a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
214b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
214c0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
214d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
214e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
214f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
21500 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
21510 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
21520 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
21530 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
21540 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
21550 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
21560 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
21570 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
21580 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
21590 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
215a0 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
215b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
215c0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
215d0 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
215e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
215f0 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
21600 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
21610 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
21620 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21630 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
21640 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21650 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
21660 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
21670 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21680 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
21690 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
216a0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
216b0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
216c0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
216d0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
216e0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
216f0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
21700 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
21710 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21720 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
21730 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
21740 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
21750 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
21760 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
21770 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
21780 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
21790 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
217a0 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
217b0 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
217c0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
217d0 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
217e0 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
217f0 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
21800 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
21810 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
21820 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
21830 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
21840 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
21850 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
21860 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
21870 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
21880 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
21890 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
218a0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
218b0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
218c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
218d0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
218e0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
218f0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21900 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
21910 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
21920 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
21930 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21940 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
21950 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
21960 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
21970 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
21980 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
21990 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
219a0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
219b0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
219c0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
219d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
219e0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
219f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21a00 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
21a10 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
21a20 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
21a30 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21a40 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
21a50 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
21a60 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
21a70 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
21a80 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
21a90 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
21aa0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
21ab0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
21ac0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
21ad0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21ae0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21af0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21b00 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21b10 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21b20 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21b30 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21b40 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21b50 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21b60 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21b70 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
21b80 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
21b90 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
21ba0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
21bb0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
21bc0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21bd0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
21be0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
21bf0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21c00 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21c10 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21c20 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21c30 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21c40 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21c50 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
21c60 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
21c70 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
21c80 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
21c90 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
21ca0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
21cb0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
21cc0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
21cd0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
21ce0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
21cf0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21d00 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21d10 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21d20 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21d30 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21d50 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21d60 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21d70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21d80 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
21d90 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
21da0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
21db0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
21dc0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
21dd0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
21de0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
21df0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21e00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21e10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21e20 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21e30 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21e40 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21e50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21e60 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21e70 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
21e80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
21e90 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
21ea0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21eb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
21ec0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
21ed0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21ef0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21f00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21f10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21f20 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21f30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21f40 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21f50 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21f60 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21f70 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
21f80 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
21f90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
21fa0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
21fb0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
21fc0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
21fd0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
21fe0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
21ff0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
22000 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
22010 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
22020 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
22030 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
22040 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
22050 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22060 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
22070 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
22080 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
22090 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
220a0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
220b0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
220c0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
220d0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
220e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
220f0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
22100 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
22110 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
22120 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22130 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
22140 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
22150 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
22160 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
22170 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
22180 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
22190 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
221a0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
221b0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
221c0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
221d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
221e0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
221f0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
22200 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
22210 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22220 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
22230 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22240 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22250 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
22260 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22270 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
22280 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
22290 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
222a0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
222b0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
222c0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
222d0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
222e0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
222f0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
22300 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22310 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
22320 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
22330 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
22340 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22350 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22360 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
22370 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
22380 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
22390 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
223a0 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
223b0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
223c0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
223d0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
223e0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
223f0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
22400 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
22410 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
22420 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
22430 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
22440 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
22450 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
22460 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
22470 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
22480 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22490 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
224a0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
224b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
224c0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
224d0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
224e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
224f0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
22500 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
22510 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
22520 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
22530 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
22540 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22550 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
22560 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
22570 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
22580 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
22590 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
225a0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
225b0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
225c0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
225d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
225e0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
225f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
22600 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
22610 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
22620 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
22630 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
22640 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
22650 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
22660 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
22670 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
22680 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
22690 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
226a0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
226b0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
226c0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
226d0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
226e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
226f0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
22700 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
22710 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22720 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
22730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
22740 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
22750 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
22760 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
22770 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22780 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22790 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
227a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
227b0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
227c0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
227d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
227e0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
227f0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
22800 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
22810 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
22820 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
22830 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
22840 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
22850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22860 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
22870 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
22880 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
228a0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
228b0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
228c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
228f0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
22900 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
22910 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22940 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
22950 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
22960 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22970 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22990 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
229a0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
229b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
229c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
229e0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
229f0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
22a00 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22a10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22a30 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22a40 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
22a50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22a60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22a80 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
22a90 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22aa0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22ac0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22ad0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
22ae0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22af0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b10 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
22b20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
22b30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22b40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b60 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
22b70 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
22b80 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22b90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22bb0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
22bc0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
22bd0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c00 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
22c10 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
22c20 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22c30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c50 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
22c60 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
22c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22c80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ca0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
22cb0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
22cc0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22cd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cf0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
22d00 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
22d10 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22d20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d40 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
22d50 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
22d60 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22d70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22d90 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
22da0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
22db0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22dc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
22de0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
22df0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
22e00 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22e10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
22e30 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
22e40 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
22e50 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
22e60 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
22e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
22e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22e90 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
22ea0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22eb0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22ec0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
22ed0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22ee0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
22ef0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22f00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22f10 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
22f20 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
22f30 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22f40 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22f50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22f60 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
22f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
22f80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22f90 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22fa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22fb0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
22fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
22fd0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
22fe0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22ff0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23000 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
23010 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
23020 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
23030 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
23040 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23050 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
23060 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
23070 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
23080 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
230a0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
230b0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
230c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
230d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
230e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
230f0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
23100 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
23110 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23140 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
23150 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
23160 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23170 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
23180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23190 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
231a0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
231b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
231c0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
231d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
231e0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
231f0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
23200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
23210 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
23220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23230 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
23240 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
23250 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
23260 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
23270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23280 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
23290 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
232a0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
232b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
232c0 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
232d0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
232e0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
232f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
23300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
23310 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
23320 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
23330 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23340 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23350 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
23360 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
23370 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23380 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
23390 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
233a0 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
233b0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
233c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
233d0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
233e0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
233f0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
23400 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
23410 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
23420 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
23430 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
23440 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
23450 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
23460 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
23470 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
23480 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
23490 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
234a0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
234b0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
234c0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
234d0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
234e0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
234f0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
23500 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
23510 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
23520 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
23530 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
23540 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
23550 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
23560 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
23570 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
23580 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
23590 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
235a0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
235b0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
235c0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
235d0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
235e0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
235f0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
23600 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
23610 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
23620 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
23630 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
23640 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
23650 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
23660 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
23670 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
23680 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
23690 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
236a0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
236b0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
236c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
236d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
236e0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
236f0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
23700 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
23710 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
23720 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
23730 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23740 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
23750 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
23760 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
23770 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
23780 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
23790 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
237a0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
237b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
237c0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
237d0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
237e0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
237f0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
23800 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
23810 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
23820 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
23830 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23840 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
23850 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
23860 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
23870 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23880 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23890 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
238a0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
238b0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
238c0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
238d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
238e0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
238f0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
23900 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
23910 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
23920 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
23930 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23940 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
23950 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23960 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
23970 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23980 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
23990 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
239a0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
239b0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
239c0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
239d0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
239e0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
239f0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
23a00 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
23a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23a20 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
23a30 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
23a40 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
23a50 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
23a60 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
23a70 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
23a80 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
23a90 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
23aa0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
23ab0 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
23ac0 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
23ad0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
23ae0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
23af0 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e  race_v2()] is an
23b00 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
23b10 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
23b20 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
23b30 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23b40 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
23b50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
23b60 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
23b70 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
23b80 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23b90 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
23ba0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
23bb0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
23bc0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
23bd0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
23be0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
23bf0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
23c00 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23c10 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23c20 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23c30 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
23c40 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
23c50 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
23c60 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
23c70 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
23c80 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
23c90 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
23ca0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
23cb0 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
23cc0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
23cd0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
23ce0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23cf0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23d00 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
23d10 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
23d20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23d30 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
23d40 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23d50 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
23d60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23d70 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
23d80 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
23d90 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
23da0 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
23db0 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
23dc0 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
23dd0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
23de0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
23df0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
23e00 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
23e10 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
23e20 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
23e30 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23e40 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
23e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
23e60 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
23e70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
23e80 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
23e90 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
23ea0 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
23eb0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
23ec0 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
23ed0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
23ee0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
23ef0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
23f00 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
23f10 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
23f20 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
23f30 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
23f40 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
23f50 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
23f60 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
23f70 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
23f80 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
23f90 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
23fa0 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
23fb0 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
23fc0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
23fd0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
23fe0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
23ff0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24000 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
24010 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
24020 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
24030 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24040 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
24050 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
24060 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
24070 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
24080 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
24090 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
240a0 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
240b0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
240c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
240d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
240e0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
240f0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
24100 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
24110 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
24120 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
24130 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
24140 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
24150 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
24160 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
24170 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
24180 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
24190 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
241a0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
241b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
241c0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
241d0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
241e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
241f0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
24200 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24210 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
24220 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
24230 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
24240 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
24250 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
24260 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
24270 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
24280 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24290 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
242a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
242b0 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
242c0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
242d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
242e0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
242f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24300 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
24310 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
24320 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
24330 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
24340 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
24350 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
24360 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
24370 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24380 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
24390 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
243a0 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
243b0 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
243c0 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
243d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
243e0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
243f0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
24400 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
24410 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
24420 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
24430 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
24440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24450 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
24460 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
24470 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
24480 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
24490 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
244a0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
244b0 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
244c0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
244d0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
244e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
244f0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
24500 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
24510 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
24520 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
24530 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
24540 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
24550 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
24560 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
24570 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
24580 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
24590 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
245a0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
245b0 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
245c0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
245d0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
245e0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
245f0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
24600 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
24610 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
24620 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
24630 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
24640 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
24650 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
24660 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
24670 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
24680 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
24690 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
246a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
246b0 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
246c0 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
246d0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
246e0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
246f0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
24700 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
24710 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
24720 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
24730 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
24740 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
24750 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
24760 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
24770 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
24780 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
24790 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
247a0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
247b0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
247c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
247d0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
247e0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
247f0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
24800 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
24810 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
24820 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
24830 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
24840 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
24850 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
24860 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
24870 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
24880 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
24890 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
248a0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
248b0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
248c0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
248d0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
248e0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
248f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
24900 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
24910 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
24920 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
24930 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
24940 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
24950 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
24960 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
24970 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
24980 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
24990 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
249a0 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
249b0 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
249c0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
249d0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
249e0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
249f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
24a00 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
24a10 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
24a20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24a30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
24a40 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
24a50 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
24a60 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
24a70 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
24a80 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
24a90 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
24aa0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
24ab0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
24ac0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
24ad0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
24af0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
24b00 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24b10 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
24b20 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
24b30 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
24b40 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
24b50 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
24b60 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
24b70 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
24b80 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
24b90 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
24ba0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
24bb0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
24bc0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
24bd0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
24be0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
24bf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
24c00 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
24c10 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
24c20 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
24c30 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
24c40 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
24c50 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
24c60 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
24c70 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
24c80 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
24c90 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
24ca0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24cb0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
24cc0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
24cd0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
24ce0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
24cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24d00 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
24d10 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
24d20 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
24d30 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
24d40 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
24d50 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
24d60 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
24d70 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
24d80 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
24d90 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
24da0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
24db0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
24dc0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
24dd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
24de0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
24df0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
24e00 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
24e10 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
24e20 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
24e30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
24e40 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
24e50 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
24e60 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
24e70 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
24e80 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
24e90 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
24ea0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
24eb0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
24ec0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
24ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24ee0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
24ef0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24f00 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
24f10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24f20 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
24f30 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
24f40 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
24f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24f60 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
24f70 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
24f80 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
24f90 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
24fa0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24fb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
24fc0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
24fd0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
24fe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24ff0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
25000 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
25010 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
25020 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25030 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
25040 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
25050 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
25060 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
25070 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
25080 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
25090 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
250a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
250b0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
250c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
250d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
250e0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
250f0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
25100 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
25110 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
25120 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
25130 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
25140 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
25150 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
25160 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
25170 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
25180 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
25190 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
251a0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
251b0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
251c0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
251d0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
251e0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
251f0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
25200 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
25210 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
25220 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
25230 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
25240 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25250 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
25260 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
25270 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
25280 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
25290 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
252a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
252b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
252c0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
252d0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
252e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
252f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
25300 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
25310 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
25320 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
25330 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
25340 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
25350 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
25360 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
25370 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
25380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
25390 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
253a0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
253b0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
253c0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
253d0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
253e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
253f0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
25400 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
25410 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
25420 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
25430 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
25440 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
25450 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
25460 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
25470 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
25480 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
25490 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
254a0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
254b0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
254c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
254d0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
254e0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
254f0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
25500 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
25510 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
25520 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
25530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
25540 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
25550 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
25560 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
25570 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
25580 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
25590 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
255a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
255b0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
255c0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
255d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
255e0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
255f0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
25600 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
25610 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
25620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
25630 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
25640 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25650 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
25660 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
25670 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
25680 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
25690 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
256a0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
256b0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
256c0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
256d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
256e0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
256f0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
25700 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25710 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25720 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25730 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
25740 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
25750 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
25760 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
25770 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
25780 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
25790 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
257a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
257b0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
257c0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
257d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
257e0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
257f0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
25800 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
25810 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
25820 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
25830 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
25840 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
25850 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
25860 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
25870 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
25880 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
25890 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
258a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
258b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
258c0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
258d0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
258e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
258f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25900 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25910 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
25920 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
25930 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
25940 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
25950 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
25960 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
25970 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
25980 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
25990 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
259a0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
259b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
259c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
259d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
259e0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
259f0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
25a00 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
25a10 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
25a20 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
25a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25a40 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
25a50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
25a60 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25a70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25a80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
25a90 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
25aa0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
25ab0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
25ad0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
25ae0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
25af0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
25b00 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
25b10 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
25b20 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
25b30 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
25b40 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
25b50 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
25b60 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
25b70 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
25b80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
25ba0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
25bb0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25bc0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
25bd0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
25be0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
25bf0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
25c00 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
25c10 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
25c20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25c30 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
25c40 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25c60 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
25c70 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
25c80 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
25c90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25ca0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
25cb0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
25cc0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
25cd0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
25ce0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
25cf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25d00 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
25d10 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25d30 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
25d40 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
25d50 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
25d60 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
25d70 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
25d80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25d90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25da0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
25db0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
25dc0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
25dd0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
25de0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25df0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25e00 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
25e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25e20 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
25e30 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
25e40 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
25e50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25e60 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
25e70 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25e80 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
25e90 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
25ea0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
25eb0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25ec0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
25ed0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
25ee0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
25ef0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
25f00 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
25f10 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
25f20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
25f30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25f40 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
25f50 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25f60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
25f70 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
25f80 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
25f90 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
25fa0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
25fb0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
25fc0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
25fd0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
25fe0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25ff0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
26000 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
26010 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
26020 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
26030 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
26040 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
26050 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
26060 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
26070 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
26080 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
26090 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
260a0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
260b0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
260c0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
260d0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
260e0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
260f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
26100 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
26110 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
26120 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
26130 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
26140 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
26150 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
26160 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
26170 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
26180 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
26190 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
261a0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
261b0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
261c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
261d0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
261e0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
261f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26200 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26210 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
26220 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
26230 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
26240 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
26250 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
26260 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
26270 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
26280 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26290 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
262a0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
262b0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
262c0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
262d0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
262e0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
262f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
26300 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
26310 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
26320 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
26330 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
26340 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
26350 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
26360 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
26370 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
26380 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
26390 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
263a0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
263b0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
263c0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
263d0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
263e0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
263f0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
26400 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
26410 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
26420 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
26430 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
26440 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
26450 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
26460 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
26470 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
26480 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
26490 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
264a0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
264b0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
264c0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
264d0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
264e0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
264f0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
26500 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26510 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
26520 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
26530 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
26540 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
26550 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
26560 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
26570 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
26580 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
26590 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
265a0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
265b0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
265c0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
265d0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
265e0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
265f0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
26600 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26610 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
26620 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
26630 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
26640 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
26650 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
26660 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
26670 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
26680 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
26690 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
266a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
266b0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
266c0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
266d0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
266e0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
266f0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
26700 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
26710 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
26720 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
26730 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
26740 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
26750 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
26760 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
26770 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
26780 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
26790 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
267a0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
267b0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
267c0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
267d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
267e0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
267f0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
26800 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
26810 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
26820 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
26830 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
26840 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
26850 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
26860 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
26870 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
26880 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
26890 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
268a0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
268b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
268c0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
268d0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
268e0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
268f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
26900 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
26910 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
26920 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
26930 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
26940 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
26950 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
26960 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
26970 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
26980 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
26990 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
269a0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
269b0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
269c0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
269d0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
269e0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
269f0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
26a00 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
26a10 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
26a20 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
26a30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26a40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26a50 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
26a60 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
26a70 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
26a80 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
26a90 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
26aa0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
26ab0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
26ac0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
26ad0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
26ae0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
26af0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
26b00 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
26b10 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
26b20 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26b30 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
26b40 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
26b50 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
26b60 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
26b70 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
26b80 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
26b90 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
26ba0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
26bb0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
26bc0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
26bd0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
26be0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
26bf0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26c00 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
26c10 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
26c20 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
26c30 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
26c40 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
26c50 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
26c60 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
26c70 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
26c80 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
26c90 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
26ca0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
26cb0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
26cc0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
26cd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
26ce0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
26cf0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
26d00 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
26d10 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
26d20 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
26d30 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
26d40 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
26d50 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
26d60 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
26d70 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
26d80 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
26d90 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
26da0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
26db0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
26dc0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
26dd0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
26de0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
26df0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
26e00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
26e20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
26e30 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
26e40 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
26e50 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
26e60 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
26e70 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
26e80 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
26e90 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
26ea0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
26eb0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
26ec0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
26ed0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
26ee0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
26ef0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
26f00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26f10 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
26f20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26f30 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
26f40 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
26f50 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
26f60 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
26f70 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
26f80 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
26f90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26fa0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
26fb0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
26fc0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
26fd0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
26fe0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
26ff0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
27000 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
27010 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
27020 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
27030 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
27040 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
27050 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
27060 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
27070 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
27080 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
27090 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
270a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
270b0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
270c0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
270d0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
270e0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
270f0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
27100 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
27110 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
27120 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
27130 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
27140 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
27150 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
27160 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
27170 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
27180 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
27190 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
271a0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
271b0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
271c0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
271d0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
271e0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
271f0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
27200 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
27210 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
27220 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
27230 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
27240 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
27250 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
27260 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
27270 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
27280 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
27290 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
272a0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
272b0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
272c0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
272d0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
272e0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
272f0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
27300 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
27310 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
27320 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
27330 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
27340 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
27350 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
27360 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
27370 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
27380 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
27390 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
273a0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
273b0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
273c0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
273d0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
273e0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
273f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27400 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
27410 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
27420 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
27430 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
27440 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
27450 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
27460 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
27470 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
27480 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
27490 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
274a0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
274b0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
274c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
274d0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
274e0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
274f0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
27500 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
27510 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
27520 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
27530 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
27540 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
27550 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
27560 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
27570 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
27580 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
27590 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
275a0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
275b0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
275c0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
275d0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
275e0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
275f0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
27600 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
27610 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
27620 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27630 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
27640 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
27650 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
27660 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
27670 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
27680 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
27690 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
276a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
276b0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
276c0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
276d0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
276e0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
276f0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
27700 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
27710 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
27720 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
27730 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
27740 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
27750 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
27760 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27770 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
27780 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
27790 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
277a0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
277b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
277c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
277d0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
277e0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
277f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
27800 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
27810 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
27820 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
27830 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
27840 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
27850 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
27860 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
27870 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
27880 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
27890 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
278a0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
278b0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
278c0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
278d0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
278e0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
278f0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27900 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
27910 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
27920 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
27930 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
27940 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
27950 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
27960 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
27970 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
27980 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
27990 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
279a0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
279b0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
279c0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
279d0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
279e0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
279f0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
27a00 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
27a10 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
27a20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
27a30 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
27a40 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
27a50 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
27a60 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
27a70 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
27a80 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
27a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
27aa0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
27ab0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
27ac0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
27ad0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
27ae0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
27af0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
27b00 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
27b10 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
27b20 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
27b30 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
27b40 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
27b50 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
27b60 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
27b70 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
27b80 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
27b90 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
27ba0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
27bb0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27bc0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
27bd0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
27be0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
27bf0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
27c00 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
27c10 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
27c20 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27c30 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
27c40 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
27c50 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
27c60 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
27c70 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
27c80 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
27c90 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
27ca0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
27cb0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
27cc0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
27cd0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
27ce0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
27cf0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
27d00 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
27d10 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
27d20 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
27d30 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
27d40 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
27d50 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
27d60 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
27d70 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
27d80 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
27d90 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
27da0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
27db0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
27dc0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
27dd0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
27de0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
27df0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
27e00 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
27e10 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
27e20 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
27e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
27e40 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
27e50 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
27e60 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
27e70 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
27e80 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
27e90 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
27ea0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
27eb0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
27ec0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
27ed0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
27ee0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
27ef0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
27f00 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
27f10 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
27f20 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
27f30 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
27f40 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
27f50 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
27f60 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
27f70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
27f80 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
27f90 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
27fa0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
27fb0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
27fc0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
27fd0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
27fe0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
27ff0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
28000 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
28010 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
28020 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
28030 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
28040 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
28050 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
28060 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28070 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
28080 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
28090 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
280a0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
280b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
280c0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
280d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
280e0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
280f0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28100 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
28110 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
28120 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
28130 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
28140 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
28150 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
28160 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
28170 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
28180 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
28190 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
281a0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
281b0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
281c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
281d0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
281e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
281f0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
28200 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28210 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
28220 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
28230 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
28240 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
28250 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
28260 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
28270 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
28280 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
28290 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
282a0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
282b0 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
282c0 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
282d0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
282e0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
282f0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
28300 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
28310 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
28320 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
28330 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
28340 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
28350 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
28360 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
28370 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
28380 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
28390 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
283a0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
283b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
283c0 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
283d0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
283e0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
283f0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
28400 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
28410 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
28420 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
28430 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
28440 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
28450 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
28460 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
28470 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
28480 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
28490 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
284a0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
284b0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
284c0 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
284d0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
284e0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
284f0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
28500 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
28510 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
28520 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
28530 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
28540 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
28550 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
28560 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
28570 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
28580 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
28590 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
285a0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
285b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
285c0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
285d0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
285e0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
285f0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
28600 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
28610 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
28620 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
28630 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
28640 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
28650 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28660 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
28670 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
28680 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
28690 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
286a0 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
286b0 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
286c0 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
286d0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
286e0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
286f0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
28700 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
28710 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28720 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
28730 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
28740 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
28750 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
28760 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
28770 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
28780 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
28790 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
287a0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
287b0 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
287c0 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
287d0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
287e0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
287f0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
28800 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
28810 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
28820 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
28830 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28840 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
28850 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
28860 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
28870 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
28880 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
28890 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
288a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
288b0 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
288c0 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
288d0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
288e0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
288f0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
28900 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
28910 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
28920 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
28930 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
28940 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
28950 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
28960 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
28970 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
28980 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
28990 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
289a0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
289b0 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
289c0 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
289d0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
289e0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
289f0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
28a00 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
28a10 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
28a20 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
28a30 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
28a40 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
28a50 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
28a60 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
28a70 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
28a80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
28a90 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28aa0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
28ab0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
28ac0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
28ad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
28ae0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
28af0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
28b00 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
28b10 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
28b20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
28b30 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
28b40 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
28b50 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
28b60 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
28b70 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
28b80 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
28b90 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
28ba0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
28bb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
28bc0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
28bd0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
28be0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
28bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
28c00 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
28c10 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
28c20 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
28c30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
28c40 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
28c50 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
28c60 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
28c70 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
28c80 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
28c90 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
28ca0 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
28cb0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
28cc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
28cd0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28ce0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
28cf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28d00 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
28d10 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
28d20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
28d30 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
28d40 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
28d50 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
28d60 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
28d70 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
28d80 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
28d90 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
28da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
28db0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
28dc0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
28dd0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
28de0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
28df0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
28e00 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
28e10 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
28e20 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
28e30 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28e40 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28e50 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28e60 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
28e70 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
28e80 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
28e90 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
28ea0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
28eb0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
28ec0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
28ed0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
28ee0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
28ef0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
28f00 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
28f10 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
28f20 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
28f30 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
28f40 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
28f50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28f60 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
28f70 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
28f80 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
28f90 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
28fa0 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
28fb0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
28fc0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28fd0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
28fe0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
28ff0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
29000 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
29010 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
29020 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
29030 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
29040 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
29050 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
29060 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
29070 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
29080 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
29090 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
290a0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
290b0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
290c0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
290d0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
290e0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
290f0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
29100 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
29110 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
29120 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
29130 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
29140 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
29150 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
29160 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
29170 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
29180 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
29190 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
291a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
291b0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
291c0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
291d0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
291e0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
291f0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
29200 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
29210 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
29220 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
29230 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
29240 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
29250 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
29260 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
29270 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
29280 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
29290 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
292a0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
292b0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
292c0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
292d0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
292e0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
292f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
29300 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
29310 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
29320 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
29330 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
29340 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
29350 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
29360 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
29370 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
29380 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
29390 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
293a0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
293b0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
293c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
293d0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
293e0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
293f0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
29400 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
29410 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
29420 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
29430 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
29440 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29450 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
29460 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
29470 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
29480 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
29490 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
294a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
294b0 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
294c0 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
294d0 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
294e0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
294f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
29500 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
29510 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
29520 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
29530 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
29540 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
29550 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
29560 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
29570 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
29580 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
29590 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
295a0 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
295b0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
295c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
295d0 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
295e0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
295f0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
29600 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
29610 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29620 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
29630 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
29640 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
29650 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
29660 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29670 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29680 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
29690 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
296a0 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
296b0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
296c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
296d0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
296e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
296f0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
29700 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29710 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
29720 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
29730 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
29740 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
29750 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29760 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
29770 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
29780 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
29790 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
297a0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
297b0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
297c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
297d0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
297e0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
297f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
29800 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
29810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
29820 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
29830 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29840 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
29850 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
29860 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
29870 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
29880 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
29890 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
298a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
298b0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
298c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
298d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
298e0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
298f0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
29900 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
29910 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
29920 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
29930 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
29940 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
29950 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
29960 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
29970 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
29980 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
29990 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
299a0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
299b0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
299c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
299d0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
299e0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
299f0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
29a00 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
29a10 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
29a20 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
29a30 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
29a40 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
29a50 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
29a60 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
29a70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
29a80 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
29a90 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
29aa0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
29ab0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
29ac0 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
29ad0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
29ae0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
29af0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
29b00 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
29b10 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
29b20 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
29b30 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
29b40 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
29b50 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
29b60 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
29b70 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
29b80 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
29b90 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
29ba0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
29bb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
29bc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29bd0 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
29be0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
29bf0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
29c00 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
29c10 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
29c20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
29c30 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
29c40 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
29c50 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
29c60 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
29c70 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
29c80 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
29c90 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
29ca0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
29cb0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
29cc0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
29cd0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
29ce0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
29cf0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
29d00 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
29d10 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
29d20 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
29d30 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
29d40 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
29d50 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
29d60 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
29d70 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
29d80 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
29d90 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
29da0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
29db0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
29dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
29dd0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
29de0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
29df0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
29e00 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
29e10 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
29e20 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
29e30 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
29e40 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
29e50 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
29e60 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
29e70 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
29e80 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
29e90 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
29ea0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
29eb0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
29ec0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
29ed0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
29ee0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
29ef0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
29f00 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
29f10 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
29f20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
29f30 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
29f40 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
29f50 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
29f60 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
29f70 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
29f80 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
29f90 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
29fa0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
29fb0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
29fc0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
29fd0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
29fe0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
29ff0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
2a000 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
2a010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a020 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
2a030 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
2a040 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
2a050 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
2a060 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
2a070 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2a080 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2a090 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
2a0a0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
2a0b0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
2a0c0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
2a0d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
2a0e0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
2a0f0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
2a100 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
2a110 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
2a120 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
2a130 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
2a140 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
2a150 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
2a160 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
2a170 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2a180 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2a190 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a1a0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
2a1b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a1c0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
2a1d0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
2a1e0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
2a1f0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
2a200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a210 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
2a220 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a230 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
2a240 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a250 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
2a260 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2a270 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
2a280 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a290 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
2a2a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a2b0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
2a2c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a2d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2a2e0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
2a2f0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
2a300 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
2a310 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2a320 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
2a330 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2a340 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
2a350 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
2a360 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
2a370 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
2a380 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a390 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
2a3a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a3b0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
2a3c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a3d0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
2a3e0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
2a3f0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
2a400 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2a420 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
2a430 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a440 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2a450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a460 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a470 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
2a480 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
2a490 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
2a4a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a4b0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
2a4c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a4d0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
2a4e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a4f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
2a500 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
2a510 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
2a520 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
2a530 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
2a540 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  L statement.  If
2a550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a560 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68  e_v2()] or.** th
2a570 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69  e equivalent tri
2a580 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73  es to allocate s
2a590 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68  pace for more th
2a5a0 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63  an this many opc
2a5b0 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e  odes.** in a sin
2a5c0 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74 61  gle prepared sta
2a5d0 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54  tement, an SQLIT
2a5e0 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73  E_NOMEM error is
2a5f0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
2a600 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a610 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a620 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
2a630 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2a640 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
2a650 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a660 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2a670 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
2a680 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a6a0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
2a6b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2a6c0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
2a6d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a6e0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
2a6f0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2a700 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
2a710 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a720 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2a730 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
2a740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2a750 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2a760 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a770 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2a780 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
2a790 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
2a7a0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
2a7b0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
2a7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a7d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a7e0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
2a7f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a800 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a810 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
2a820 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
2a830 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
2a840 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
2a850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
2a860 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a870 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2a880 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2a890 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a8a0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
2a8b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
2a8c0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
2a8d0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
2a8e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a8f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2a900 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
2a910 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a920 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
2a930 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a940 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a950 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
2a960 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
2a970 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
2a980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a990 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
2a9a0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
2a9b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a9c0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
2a9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
2a9e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a9f0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
2aa00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
2aa10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2aa20 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
2aa30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
2aa40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2aa50 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2aa60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aa70 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2aa80 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2aa90 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
2aaa0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2aab0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
2aac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aad0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
2aae0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2aaf0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
2ab00 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
2ab10 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2ab20 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
2ab30 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
2ab40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2ab50 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
2ab60 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
2ab70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2ab80 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
2ab90 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
2aba0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2abb0 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
2abc0 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
2abd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
2abe0 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
2abf0 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
2ac00 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
2ac10 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  re Flags.**.** T
2ac20 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2ac30 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c  efine various fl
2ac40 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ags that can be 
2ac50 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22  passed into.** "
2ac60 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d  prepFlags" param
2ac70 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c  eter of the [sql
2ac80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2ac90 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
2aca0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2acb0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  )] interfaces..*
2acc0 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d  *.** New flags m
2acd0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2ace0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2acf0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
2ad00 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2ad10 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2ad20 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ENT]] ^(<dt>SQLI
2ad30 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2ad40 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  STENT</dt>.** <d
2ad50 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45  d>The SQLITE_PRE
2ad60 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20  PARE_PERSISTENT 
2ad70 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20 74  flag is a hint t
2ad80 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  o the query plan
2ad90 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ner.** that the 
2ada0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2adb0 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69  nt will be retai
2adc0 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74  ned for a long t
2add0 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61  ime and.** proba
2ade0 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20  bly reused many 
2adf0 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75  times.)^ ^Withou
2ae00 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71  t this flag, [sq
2ae10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ae20 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2ae30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2ae40 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20  ()] assume that 
2ae50 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2ae60 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20  tement will .** 
2ae70 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63  be used just onc
2ae80 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66  e or at most a f
2ae90 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65  ew times and the
2aea0 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  n destroyed usin
2aeb0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
2aec0 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69  nalize()] relati
2aed0 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63  vely soon. The c
2aee0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
2aef0 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e  ation acts.** on
2af00 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61 76   this hint by av
2af10 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f  oiding the use o
2af20 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  f [lookaside mem
2af30 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74  ory] so as not t
2af40 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65  o.** deplete the
2af50 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f   limited store o
2af60 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
2af70 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73 69  ry. Future versi
2af80 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ons of.** SQLite
2af90 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73   may act on this
2afa0 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c   hint differentl
2afb0 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  y..** </dl>.*/.#
2afc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
2afd0 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2afe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
2aff0 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  01../*.** CAPI3R
2b000 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
2b010 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2b020 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2b030 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
2b040 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
2b050 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
2b060 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
2b070 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
2b080 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61  ecute an SQL sta
2b090 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20  tement, it must 
2b0a0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
2b0b0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
2b0c0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
2b0d0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
2b0e0 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20   routines.  Or, 
2b0f0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
2b100 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2b110 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f  * are constructo
2b120 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  rs for the [prep
2b130 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b140 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  object..**.** Th
2b150 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74  e preferred rout
2b160 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73  ine to use is [s
2b170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b180 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  2()].  The.** [s
2b190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b1a0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c  ] interface is l
2b1b0 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64  egacy and should
2b1c0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20   be avoided..** 
2b1d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b1e0 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78  _v3()] has an ex
2b1f0 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20  tra "prepFlags" 
2b200 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75  option that is u
2b210 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69  sed.** for speci
2b220 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  al purposes..**.
2b230 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  ** The use of th
2b240 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63  e UTF-8 interfac
2b250 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c  es is preferred,
2b260 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65   as SQLite curre
2b270 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c  ntly.** does all
2b280 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55   parsing using U
2b290 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31  TF-8.  The UTF-1
2b2a0 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  6 interfaces are
2b2b0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20   provided.** as 
2b2c0 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20  a convenience.  
2b2d0 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2b2e0 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f  faces work by co
2b2f0 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20  nverting the.** 
2b300 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20  input text into 
2b310 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f  UTF-8, then invo
2b320 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70  king the corresp
2b330 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74  onding UTF-8 int
2b340 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
2b350 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b360 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
2b370 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b380 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
2b390 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
2b3a0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2b3b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2b3c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2b3d0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
2b3e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
2b3f0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
2b400 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
2b410 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
2b420 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
2b430 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
2b440 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
2b450 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2b460 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
2b470 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
2b480 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
2b490 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2b4a0 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  e(), sqlite3_pre
2b4b0 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  pare_v2(),.** an
2b4c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2b4d0 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v3().** interf
2b4e0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
2b4f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b500 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33  are16(), sqlite3
2b510 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2b520 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2b530 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75  prepare16_v3() u
2b540 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
2b550 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
2b560 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74  rgument is negat
2b570 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ive, then zSql i
2b580 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
2b590 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
2b5a0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
2b5b0 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65  Byte is positive
2b5c0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
2b5d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2b5e0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
2b5f0 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69  ql.  ^If nByte i
2b600 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20  s zero, then no 
2b610 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2b620 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74  ement is generat
2b630 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
2b640 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20  ller knows that 
2b650 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
2b660 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
2b670 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74  nated, then.** t
2b680 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20  here is a small 
2b690 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
2b6a0 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67  ntage to passing
2b6b0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
2b6c0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74  ter that.** is t
2b6d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b6e0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
2b6f0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
2b700 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
2b710 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ul-terminator..*
2b720 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
2b730 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
2b740 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
2b750 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
2b760 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
2b770 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
2b780 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
2b790 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
2b7a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b7b0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
2b7c0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
2b7d0 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
2b7e0 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
2b7f0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
2b800 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
2b810 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
2b820 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
2b830 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
2b840 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
2b850 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b860 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
2b870 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2b880 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
2b890 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
2b8a0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
2b8b0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
2b8c0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
2b8d0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
2b8e0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
2b8f0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
2b900 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
2b910 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
2b920 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
2b930 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
2b940 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
2b950 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
2b960 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
2b970 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2b980 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2b990 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
2b9a0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
2b9b0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
2b9c0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
2b9d0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2b9e0 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
2b9f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2ba00 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
2ba10 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2ba20 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
2ba30 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
2ba40 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2ba50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2ba60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ba70 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2ba80 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33  re_v3(), sqlite3
2ba90 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2baa0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2bab0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69  prepare16_v3() i
2bac0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
2bad0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2bae0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a  l new programs..
2baf0 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74  ** The older int
2bb00 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33  erfaces (sqlite3
2bb10 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
2bb20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bb30 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69  ()).** are retai
2bb40 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
2bb50 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2bb60 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2bb70 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2bb80 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69  * ^In the "vX" i
2bb90 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2bba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bbb0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2bbc0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2bbd0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2bbe0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2bbf0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2bc00 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2bc10 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2bc20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bc30 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2bc40 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2bc50 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2bc60 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2bc70 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2bc80 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2bc90 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2bca0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2bcb0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2bcc0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2bcd0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2bce0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2bcf0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2bd00 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2bd10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2bd20 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2bd30 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2bd40 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2bd50 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2bd60 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2bd70 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2bd80 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2bd90 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2bda0 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2bdb0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2bdc0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2bdd0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2bde0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2bdf0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2be00 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2be10 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2be20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2be30 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2be40 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2be50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2be60 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2be70 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2be80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2be90 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2bea0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2beb0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2bec0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2bed0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2bee0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2bef0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2bf00 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2bf10 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2bf20 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2bf30 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2bf40 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2bf50 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2bf60 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2bf70 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2bf80 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2bf90 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2bfa0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2bfb0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2bfc0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2bfd0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2bfe0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2bff0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2c000 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2c010 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2c020 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2c030 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2c040 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2c050 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2c060 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2c070 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2c080 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2c090 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2c0a0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2c0b0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2c0c0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2c0d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c0e0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2c0f0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2c100 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2c110 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2c120 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2c130 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2c140 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2c150 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2c160 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2c170 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2c180 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2c190 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2c1a0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2c1b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2c1c0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2c1d0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2c1e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2c1f0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2c200 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c210 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2c220 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2c230 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65   <p>^sqlite3_pre
2c240 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72  pare_v3() differ
2c250 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70  s from sqlite3_p
2c260 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79  repare_v2() only
2c270 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68   in having.** th
2c280 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67  e extra prepFlag
2c290 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  s parameter, whi
2c2a0 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61  ch is a bit arra
2c2b0 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20  y consisting of 
2c2c0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20  zero or.** more 
2c2d0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50  of the [SQLITE_P
2c2e0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c2f0 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  T|SQLITE_PREPARE
2c300 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65  _*] flags.  ^The
2c310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2c320 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  are_v2() interfa
2c330 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  ce works exactly
2c340 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
2c350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c360 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f  v3() with a zero
2c370 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2c380 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  eter..** </ol>.*
2c390 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
2c3a0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2c3b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c3c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c3d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c3e0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2c3f0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2c400 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2c410 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2c420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c430 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2c440 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2c450 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2c460 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c470 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c480 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c490 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2c4a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c4b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c4c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c4d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2c4e0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2c4f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c500 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c510 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2c530 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c540 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2c550 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2c560 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2c570 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2c580 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2c590 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2c5a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2c5b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2c5c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2c5d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2c5e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c5f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c600 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c610 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2c620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c630 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2c640 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c650 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c660 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c670 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c680 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c690 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c6a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c6b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c6c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c6d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c6e0 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  .  unsigned int 
2c6f0 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65  prepFlags, /* Ze
2c700 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54  ro or more SQLIT
2c710 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73  E_PREPARE_ flags
2c720 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c730 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c740 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c750 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c760 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2c770 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c780 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c790 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c7a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c7b0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2c7c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c7d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c7e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c7f0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2c800 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c810 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2c820 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c830 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c840 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c850 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c860 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2c870 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2c880 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2c890 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2c8a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2c8b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2c8c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2c8d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2c8e0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2c8f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c900 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2c910 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2c920 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2c930 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2c940 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2c950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c960 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2c970 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c990 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c9a0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c9b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c9c0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c9d0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c9f0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2ca00 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2ca10 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2ca20 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ca30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2ca40 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73  repare16_v3(.  s
2ca50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ca60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ca70 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ca80 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2ca90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2caa0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2cab0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2cac0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2cad0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2cae0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2caf0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2cb00 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2cb10 61 6c 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  algs, /* Zero or
2cb20 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2cb30 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2cb40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2cb50 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2cb60 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2cb70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cb80 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2cb90 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2cba0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cbb0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2cbc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cbd0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2cbe0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2cbf0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2cc00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cc10 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2cc20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cc30 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2cc40 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2cc50 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2cc60 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2cc70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2cc80 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2cc90 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2cca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2ccb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ccc0 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
2ccd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cce0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2ccf0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
2cd00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cd10 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2cd20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cd30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cd40 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2cd50 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2cd60 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2cd70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cd80 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2cd90 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2cda0 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2cdb0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2cdc0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cdd0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2cde0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2cdf0 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2ce00 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2ce10 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2ce20 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2ce30 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2ce40 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2ce50 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2ce60 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2ce70 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2ce80 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2ce90 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2cea0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2ceb0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2cec0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2ced0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2cee0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2cef0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2cf00 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2cf10 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2cf20 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2cf30 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2cf40 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2cf50 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2cf60 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2cf70 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2cf80 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2cf90 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2cfa0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2cfb0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2cfc0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2cfd0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2cfe0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2cff0 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2d000 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2d010 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2d020 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2d030 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2d040 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2d050 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2d060 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2d070 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2d080 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2d090 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2d0a0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d0b0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2d0c0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2d0d0 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2d0e0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2d0f0 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2d100 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2d110 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2d120 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2d130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2d140 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2d150 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2d160 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2d170 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d180 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2d190 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2d1a0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2d1b0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2d1c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2d1d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2d1e0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2d1f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d200 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2d210 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2d220 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d230 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d240 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2d250 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2d260 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2d270 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2d280 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d290 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d2a0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d2b0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2d2c0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2d2d0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2d2e0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2d2f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d300 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2d310 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2d320 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2d330 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2d340 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d350 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2d360 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d370 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2d380 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2d390 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2d3a0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2d3b0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2d3c0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2d3d0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2d3e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2d3f0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2d400 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2d410 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2d420 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2d430 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2d440 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2d450 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d460 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2d470 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2d480 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2d490 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2d4a0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2d4b0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2d4c0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2d4d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2d4e0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2d4f0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2d500 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2d510 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2d520 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2d530 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2d540 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2d550 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2d560 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2d570 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2d580 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2d590 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2d5a0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2d5b0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2d5c0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2d5d0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2d5e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d5f0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2d600 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2d610 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2d620 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2d630 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2d640 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2d650 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2d660 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2d670 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2d680 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2d690 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2d6a0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2d6b0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2d6c0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2d6d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2d6e0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2d6f0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2d700 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2d710 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2d720 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2d730 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2d740 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2d750 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2d760 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2d770 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2d780 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2d790 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2d7a0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2d7b0 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2d7c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2d7d0 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2d7e0 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2d7f0 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2d800 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2d810 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2d820 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2d830 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2d840 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2d850 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2d860 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2d870 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2d880 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2d890 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2d8a0 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2d8b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2d8c0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2d8d0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2d8e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d8f0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2d900 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d910 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2d920 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d930 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d940 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d950 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2d960 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2d970 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2d980 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2d990 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2d9a0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2d9b0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2d9c0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2d9d0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2d9e0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2d9f0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2da00 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2da10 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2da20 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2da30 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2da40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2da50 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2da60 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2da70 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2da80 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2da90 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2daa0 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2dab0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2dac0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2dad0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2dae0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2daf0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2db00 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2db10 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2db20 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2db30 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2db40 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2db50 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2db60 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2db70 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2db80 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2db90 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2dba0 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2dbb0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2dbc0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2dbd0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2dbe0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2dbf0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2dc00 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2dc10 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2dc20 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2dc30 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2dc40 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2dc50 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2dc60 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2dc70 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2dc80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2dc90 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2dca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dcb0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2dcc0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2dcd0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2dce0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2dcf0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2dd00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2dd10 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2dd20 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2dd30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2dd40 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2dd50 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2dd60 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2dd70 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2dd80 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2dd90 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2dda0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2ddb0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2ddc0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2ddd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dde0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2ddf0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2de00 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2de10 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2de20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2de30 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2de40 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2de50 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2de60 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2de70 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2de80 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2de90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dea0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2deb0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2dec0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2ded0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2dee0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2def0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2df00 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2df10 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2df20 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2df30 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2df40 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2df50 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2df60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2df70 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2df80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2df90 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2dfa0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2dfb0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2dfc0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2dfd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2dfe0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2dff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2e000 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2e010 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2e020 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2e030 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2e040 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2e050 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2e060 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2e070 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2e080 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2e090 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2e0a0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2e0b0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2e0c0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2e0d0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2e0e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2e0f0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2e100 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2e110 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2e120 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2e130 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2e140 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2e150 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2e160 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2e170 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2e180 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2e190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2e1a0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2e1b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2e1c0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2e1d0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2e1e0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2e1f0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2e200 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e220 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2e230 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2e240 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2e250 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2e260 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2e270 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2e280 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2e290 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2e2a0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2e2b0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2e2c0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2e2d0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e2e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e2f0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2e300 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2e310 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2e320 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e330 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2e340 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2e350 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2e360 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2e370 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2e380 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e390 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2e3a0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2e3b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e3c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2e3d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e3e0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2e3f0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2e400 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e410 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2e420 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2e430 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2e440 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2e450 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2e460 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2e470 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e480 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2e490 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2e4a0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2e4b0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2e4c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e4d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2e4e0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2e4f0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
2e500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2e510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e520 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2e530 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2e540 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2e550 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2e560 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2e570 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2e580 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2e590 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2e5a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2e5b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2e5c0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2e5d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e5e0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2e5f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e600 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2e610 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e620 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e630 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e640 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2e650 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2e660 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2e670 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2e680 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2e690 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2e6a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e6b0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2e6c0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2e6d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2e6e0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2e6f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2e700 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2e710 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2e720 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2e730 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2e740 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2e750 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2e760 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2e770 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2e780 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2e790 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2e7a0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2e7b0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2e7c0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2e7d0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2e7e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2e7f0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2e800 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2e810 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2e820 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2e830 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e840 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2e850 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2e860 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2e870 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2e880 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2e890 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2e8a0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2e8b0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2e8c0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2e8d0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2e8e0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2e8f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2e900 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2e910 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2e920 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2e930 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2e940 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2e950 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2e960 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2e970 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2e980 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2e990 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2e9a0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2e9b0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2e9c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2e9d0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2e9e0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2e9f0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2ea00 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2ea10 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2ea20 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2ea30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2ea40 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2ea50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2ea60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ea70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ea80 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2ea90 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2eaa0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2eab0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2eac0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2ead0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2eae0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2eaf0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2eb00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2eb10 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2eb20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2eb30 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2eb40 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2eb50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2eb60 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2eb70 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2eb80 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2eb90 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2eba0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2ebb0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2ebc0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2ebd0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2ebe0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2ebf0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2ec00 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2ec10 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2ec20 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2ec30 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2ec40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ec50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ec60 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2ec70 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2ec80 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2ec90 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2eca0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2ecb0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2ecc0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2ecd0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2ece0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2ecf0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2ed00 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ed10 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2ed20 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2ed30 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2ed40 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2ed50 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2ed60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2ed70 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2ed80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2ed90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2eda0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2edb0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2edc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2edd0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2ede0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2edf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ee00 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2ee10 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2ee20 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2ee30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2ee40 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2ee50 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2ee60 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2ee70 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2ee80 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2ee90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2eea0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2eeb0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2eec0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2eed0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2eee0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2eef0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2ef00 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2ef10 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2ef20 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2ef30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2ef40 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2ef50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ef60 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2ef70 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2ef80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2ef90 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2efa0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2efb0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2efc0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2efd0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2efe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2eff0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2f000 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2f010 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2f020 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2f030 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2f040 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2f050 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2f060 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2f070 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2f080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f090 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2f0a0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2f0b0 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2f0c0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2f0d0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2f0e0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2f0f0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2f100 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2f110 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2f120 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2f130 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2f140 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2f150 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2f160 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2f170 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2f180 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f190 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2f1a0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2f1b0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2f1c0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2f1d0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2f1e0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2f1f0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2f200 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2f210 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f220 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2f230 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2f240 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2f250 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2f260 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2f270 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2f280 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2f290 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2f2a0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2f2b0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2f2c0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2f2d0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2f2e0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2f2f0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2f300 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2f310 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2f320 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2f330 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2f340 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2f350 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2f360 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2f370 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2f380 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2f390 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2f3a0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2f3b0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2f3c0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2f3d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2f3e0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2f3f0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2f400 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2f410 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2f420 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2f430 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2f440 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2f450 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2f460 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2f470 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2f480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2f490 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2f4a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2f4b0 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2f4c0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2f4d0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2f4e0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2f4f0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2f500 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2f510 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2f520 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2f530 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2f540 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2f550 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2f560 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f570 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2f580 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2f590 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2f5a0 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2f5b0 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2f5c0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2f5d0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2f5e0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2f5f0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2f600 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2f610 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2f620 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f630 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2f640 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2f650 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2f660 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2f670 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2f680 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2f690 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2f6a0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2f6b0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2f6c0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2f6d0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2f6e0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2f6f0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2f700 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2f710 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2f720 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2f730 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2f740 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2f750 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2f760 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2f770 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2f780 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2f790 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2f7a0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2f7b0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2f7c0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2f7d0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2f7e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f7f0 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53  3_bind_pointer(S
2f800 2c 49 2c 50 2c 54 29 20 72 6f 75 74 69 6e 65 20  ,I,P,T) routine 
2f810 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20  causes the I-th 
2f820 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
2f830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f840 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61  ent] S to have a
2f850 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e  n SQL value of N
2f860 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f  ULL, but to also
2f870 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   be.** associate
2f880 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74  d with the point
2f890 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 0a  er P of type T..
2f8a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f8b0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
2f8c0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2f8d0 65 64 20 74 6f 20 70 61 73 73 0a 2a 2a 20 68 6f  ed to pass.** ho
2f8e0 73 74 2d 6c 61 6e 67 75 61 67 65 20 70 6f 69 6e  st-language poin
2f8f0 74 65 72 73 20 69 6e 74 6f 20 5b 61 70 70 6c 69  ters into [appli
2f900 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f910 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2f920 2a 20 5e 41 20 70 61 72 61 6d 65 74 65 72 20 74  * ^A parameter t
2f930 68 61 74 20 69 73 20 69 6e 69 74 69 61 6c 69 7a  hat is initializ
2f940 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2f950 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29  3_bind_pointer()
2f960 5d 20 61 70 70 65 61 72 73 0a 2a 2a 20 74 6f 20  ] appears.** to 
2f970 62 65 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 53  be an ordinary S
2f980 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f  QL NULL value to
2f990 20 65 76 65 72 79 74 68 69 6e 67 20 6f 74 68 65   everything othe
2f9a0 72 20 74 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  r than.** [sqlit
2f9b0 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72  e3_value_pointer
2f9c0 28 29 5d 2e 20 20 54 68 65 20 54 20 70 61 72 61  ()].  The T para
2f9d0 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
2f9e0 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 2e  a static string.
2f9f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2fa00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2fa10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2fa20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2fa30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2fa40 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2fa50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2fa60 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2fa70 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2fa80 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2fa90 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2faa0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2fab0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2fac0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2fad0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2fae0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2faf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2fb00 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2fb10 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2fb20 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2fb30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fb40 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2fb50 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2fb60 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2fb70 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2fb80 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2fb90 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2fba0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2fbb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fbc0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2fbd0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2fbe0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2fbf0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2fc00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fc10 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2fc20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2fc30 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2fc40 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2fc50 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2fc60 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2fc70 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2fc80 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2fc90 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2fca0 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2fcb0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2fcc0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2fcd0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2fce0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2fcf0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2fd00 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2fd10 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2fd20 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2fd30 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2fd40 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2fd50 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2fd60 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2fd70 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2fd80 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2fd90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2fda0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fdb0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2fdc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2fdd0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2fde0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2fdf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2fe00 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2fe10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fe20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fe30 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2fe40 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2fe50 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2fe60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2fe70 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2fe80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2fe90 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2fea0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2feb0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2fec0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2fed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2fee0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2fef0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2ff00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ff10 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2ff20 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2ff30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ff40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2ff50 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2ff60 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2ff70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2ff80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ff90 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2ffa0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2ffb0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2ffc0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2ffd0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2ffe0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fff0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30000 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30010 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30020 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30030 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
30040 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
30050 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30060 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
30070 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
30080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30090 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
300a0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
300b0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
300c0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
300d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
300e0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
300f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
30100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
30110 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
30120 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
30130 6f 6e 73 74 20 63 68 61 72 2a 29 3b 0a 69 6e 74  onst char*);.int
30140 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
30150 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
30160 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
30170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30180 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
30190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
301a0 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
301b0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
301c0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
301d0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
301e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
301f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
30200 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
30210 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
30220 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
30230 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
30240 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
30250 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
30260 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
30270 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
30280 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
30290 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
302a0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
302b0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
302c0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
302d0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
302e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
302f0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
30300 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
30310 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
30320 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
30330 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
30340 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
30350 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
30360 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
30370 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
30380 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
30390 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
303a0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
303b0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
303c0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
303d0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
303e0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
303f0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
30400 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
30410 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
30420 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30440 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30450 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30460 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30470 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
30480 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30490 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
304a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
304b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
304c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
304d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
304e0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
304f0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
30500 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30510 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30530 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
30540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30550 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
30560 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
30570 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
30580 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30590 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
305a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
305b0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
305c0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
305d0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
305e0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
305f0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
30600 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
30610 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
30620 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
30630 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
30640 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
30650 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
30660 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
30670 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
30680 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
30690 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
306a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
306b0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
306c0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
306d0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
306e0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
306f0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
30700 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
30710 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
30720 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
30730 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
30740 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
30750 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
30760 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
30770 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
30780 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
30790 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
307a0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
307b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
307c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
307d0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
307e0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
307f0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
30800 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
30810 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
30820 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
30830 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
30840 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
30850 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30860 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
30870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30880 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30890 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
308a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
308b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
308c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
308d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
308e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
308f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30900 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
30910 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30920 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30930 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30940 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
30950 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
30960 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
30970 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
30980 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
30990 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
309a0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
309b0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
309c0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
309d0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
309e0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
309f0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
30a00 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
30a10 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
30a20 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
30a30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30a40 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
30a50 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
30a60 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
30a70 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
30a80 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
30a90 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
30aa0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
30ab0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
30ac0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
30ad0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
30ae0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
30af0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
30b00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30b10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30b20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30b30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30b40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30b50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30b60 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30b70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30b80 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30b90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30ba0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30bb0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30bc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30bd0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
30be0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
30bf0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
30c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30c10 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
30c20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
30c30 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30c40 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30c50 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
30c60 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
30c70 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
30c80 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
30c90 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
30ca0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30cb0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
30cc0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30cd0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30ce0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
30cf0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
30d00 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
30d10 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
30d20 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30d30 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30d40 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30d50 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
30d60 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
30d70 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
30d80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30d90 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30da0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
30db0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
30dc0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
30dd0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
30de0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
30df0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
30e00 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
30e10 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
30e20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30e30 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
30e40 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
30e50 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
30e60 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
30e70 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
30e80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
30e90 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
30ea0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
30eb0 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
30ec0 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
30ed0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
30ee0 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
30ef0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
30f00 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
30f10 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
30f20 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
30f30 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
30f40 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
30f50 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
30f60 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
30f70 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
30f80 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
30f90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30fa0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30fb0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
30fc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
30fd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30fe0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30ff0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
31000 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
31010 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31020 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31030 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31040 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
31050 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
31060 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
31070 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
31080 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
31090 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
310a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
310b0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
310c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
310d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
310e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
310f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
31100 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31110 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
31120 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31130 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31140 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
31150 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
31160 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31180 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
31190 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
311a0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
311b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
311c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
311d0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
311e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
311f0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
31200 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
31210 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
31220 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
31230 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
31240 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31250 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
31260 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
31270 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31280 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31290 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
312a0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
312b0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
312c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
312d0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
312e0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
312f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
31300 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
31310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31320 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
31330 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
31340 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
31350 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
31360 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
31370 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
31380 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
31390 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
313a0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
313b0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
313c0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
313d0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
313e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
313f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
31400 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
31410 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
31420 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31430 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
31440 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
31450 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
31460 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
31470 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
31480 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
31490 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
314a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
314b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
314c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
314d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
314e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
314f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31510 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31520 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
31530 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
31540 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31550 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31570 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
31580 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
31590 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
315a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
315b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
315c0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
315d0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
315e0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
315f0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
31600 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
31610 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
31620 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
31630 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
31640 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31650 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
31660 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
31670 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
31680 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
31690 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
316a0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
316b0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
316c0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
316d0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
316e0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
316f0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
31700 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
31710 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
31720 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
31730 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31740 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
31750 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31760 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
31770 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
31780 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
31790 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
317a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
317b0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
317c0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
317d0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
317e0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
317f0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
31800 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31810 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
31820 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
31830 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
31840 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
31850 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
31860 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
31870 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
31880 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
31890 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
318a0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
318b0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
318c0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
318d0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
318e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
318f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
31900 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
31910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31920 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
31930 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31940 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31950 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
31960 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
31970 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
31980 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
31990 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
319a0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
319b0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
319c0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
319d0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
319e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
319f0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31a00 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
31a10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31a20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
31a30 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
31a40 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
31a50 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
31a60 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31a70 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
31a80 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
31a90 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
31aa0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
31ab0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31ac0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
31ad0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
31ae0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
31af0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
31b00 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
31b10 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
31b20 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
31b30 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
31b40 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
31b50 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
31b60 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
31b70 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
31b80 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
31b90 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
31ba0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
31bb0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
31bc0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
31bd0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
31be0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
31bf0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
31c00 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
31c10 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
31c20 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
31c30 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31c40 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
31c50 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
31c60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
31c70 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
31c80 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
31c90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31ca0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
31cb0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
31cc0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
31cd0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
31ce0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31cf0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
31d00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
31d10 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
31d20 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
31d30 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
31d40 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31d50 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
31d60 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
31d70 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
31d80 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
31d90 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
31da0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
31db0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31dc0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31dd0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31de0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
31df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31e00 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31e10 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31e20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31e30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31e40 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
31e50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31e60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31e70 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
31e80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
31e90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
31ea0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
31eb0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
31ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31ed0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
31ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
31ef0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
31f00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31f10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31f20 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
31f30 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
31f40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
31f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
31f60 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
31f70 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
31f80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31f90 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31fa0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
31fb0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
31fc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31fd0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
31fe0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
31ff0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
32000 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
32010 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
32020 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
32030 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
32040 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
32050 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
32060 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
32070 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
32080 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
32090 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
320a0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
320b0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
320c0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
320d0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
320e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
320f0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
32100 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32110 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
32120 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
32130 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
32140 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
32150 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
32160 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
32170 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
32180 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
32190 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
321a0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
321b0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
321c0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
321d0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
321e0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
321f0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
32200 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
32210 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
32220 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
32230 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
32240 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
32250 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
32260 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
32270 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
32280 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
32290 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
322a0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
322b0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
322c0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
322d0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
322e0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
322f0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
32300 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
32310 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
32320 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
32330 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
32340 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
32350 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
32360 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
32370 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
32380 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
32390 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
323a0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
323b0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
323c0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
323d0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
323e0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
323f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
32400 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32410 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
32420 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
32430 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32440 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
32450 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32460 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
32470 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
32480 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
32490 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
324a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
324b0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
324c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
324d0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
324e0 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
324f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32500 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
32510 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
32520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32530 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
32540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32550 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
32560 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
32570 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
32580 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
32590 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
325a0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
325b0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
325c0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
325d0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
325e0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
325f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
32600 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
32610 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
32620 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
32630 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
32640 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
32650 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
32660 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
32670 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
32680 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
32690 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
326a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
326b0 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
326c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
326d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
326e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
326f0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
32700 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32710 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
32720 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
32730 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
32740 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32750 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
32760 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
32770 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
32780 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
32790 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
327a0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
327b0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
327c0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
327d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
327e0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
327f0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
32800 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
32810 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
32820 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
32830 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
32840 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
32850 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
32860 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
32870 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
32880 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
32890 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
328a0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
328b0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
328c0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
328d0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
328e0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
328f0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
32900 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
32910 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
32920 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
32930 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
32940 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
32950 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
32960 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
32970 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
32980 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
32990 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
329a0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
329b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
329c0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
329d0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
329e0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
329f0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
32a00 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
32a10 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
32a20 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
32a30 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
32a40 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
32a50 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
32a60 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
32a70 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
32a80 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
32a90 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
32aa0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
32ab0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
32ac0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
32ad0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
32ae0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
32af0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
32b00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32b10 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
32b20 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
32b30 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
32b40 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
32b50 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
32b60 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
32b70 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
32b80 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
32b90 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
32ba0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
32bb0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
32bc0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
32bd0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
32be0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
32bf0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
32c00 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
32c10 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
32c20 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
32c30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32c40 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
32c50 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
32c60 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
32c70 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
32c80 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
32c90 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
32ca0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
32cb0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
32cc0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
32cd0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
32ce0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32cf0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32d00 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
32d10 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
32d20 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
32d30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32d40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
32d50 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
32d60 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
32d70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32d80 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
32d90 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
32da0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
32db0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
32dc0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
32dd0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
32de0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
32df0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
32e00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32e10 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
32e20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32e30 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
32e40 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
32e50 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
32e60 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
32e70 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
32e80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
32e90 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
32ea0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
32eb0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
32ec0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
32ed0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
32ee0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
32ef0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
32f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32f10 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
32f20 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
32f30 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
32f40 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
32f50 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
32f60 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
32f70 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
32f80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
32f90 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
32fa0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
32fb0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
32fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32fd0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
32fe0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
32ff0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
33000 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
33010 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
33020 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
33030 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
33040 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
33050 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
33060 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33070 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
33080 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
33090 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
330a0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
330b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
330c0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
330d0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
330e0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
330f0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
33100 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
33110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33120 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
33130 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
33140 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
33150 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
33160 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
33170 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
33180 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
33190 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
331a0 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
331b0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
331c0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
331d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
331e0 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
331f0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
33200 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
33210 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
33220 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
33230 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
33240 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
33250 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
33260 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
33270 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
33280 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
33290 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
332a0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
332b0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
332c0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
332d0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
332e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
332f0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
33300 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
33310 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
33320 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
33330 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
33340 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
33350 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
33360 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
33370 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
33380 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
33390 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
333a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
333b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
333c0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
333d0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
333e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
333f0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
33400 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
33410 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33420 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33430 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
33440 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
33450 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33460 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
33470 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
33480 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
33490 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
334a0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
334b0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
334c0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
334d0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
334e0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
334f0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
33500 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
33510 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
33520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
33530 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33540 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
33550 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33560 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
33570 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33580 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
33590 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
335a0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
335b0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
335c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
335d0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
335e0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
335f0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
33600 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
33610 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
33620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
33630 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
33640 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
33650 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
33660 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
33670 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
33680 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33690 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
336a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
336b0 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
336c0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
336d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
336e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
336f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33700 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
33710 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
33720 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
33730 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
33740 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
33750 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
33760 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
33770 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
33780 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
33790 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
337a0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
337b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
337c0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
337d0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
337e0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
337f0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
33800 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
33810 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
33820 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33830 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
33840 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
33850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33870 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33880 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
33890 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
338a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
338b0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
338c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
338d0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
338e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
338f0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
33900 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
33910 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
33920 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33930 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
33940 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
33950 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
33960 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
33970 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
33980 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
33990 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
339a0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
339b0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
339c0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
339d0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
339e0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
339f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33a00 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33a10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33a20 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
33a30 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33a40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33a50 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
33a60 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
33a70 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
33a80 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
33a90 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
33aa0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
33ab0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
33ac0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
33ad0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33ae0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33af0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
33b00 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
33b10 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
33b20 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
33b30 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
33b40 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
33b50 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33b60 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
33b70 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
33b80 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
33b90 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
33ba0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
33bb0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
33bc0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33bd0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
33be0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
33bf0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
33c00 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
33c10 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
33c20 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
33c30 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
33c40 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
33c50 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
33c60 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
33c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33c80 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
33c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
33ca0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
33cb0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
33cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33cd0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
33ce0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
33cf0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
33d00 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
33d10 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
33d20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
33d30 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
33d40 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
33d50 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
33d60 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
33d70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
33d80 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33d90 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
33da0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33db0 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
33dc0 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
33dd0 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
33de0 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
33df0 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
33e00 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e20 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
33e30 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
33e40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
33e60 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
33e70 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
33e80 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33ea0 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
33eb0 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
33ec0 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
33ed0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33ee0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
33ef0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
33f00 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
33f10 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33f20 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33f30 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
33f40 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
33f50 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
33f60 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33f70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
33f80 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
33f90 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
33fa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33fb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
33fc0 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
33fd0 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
33fe0 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
33ff0 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
34000 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34010 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
34020 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
34030 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
34040 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
34050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34060 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
34070 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
34080 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
34090 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
340a0 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
340b0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
340c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
340d0 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
340e0 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
340f0 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
34100 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
34110 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
34120 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34130 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
34140 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
34150 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
34160 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
34170 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
34180 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
34190 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
341a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
341b0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
341c0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
341d0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
341e0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
341f0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
34200 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
34210 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
34220 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
34230 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
34240 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34250 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
34260 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
34270 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
34280 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
34290 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
342a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
342b0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
342c0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
342d0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
342e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
342f0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
34300 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
34310 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
34320 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
34330 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
34340 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
34350 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
34360 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
34370 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
34380 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
34390 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
343a0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
343b0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
343c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
343d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
343e0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
343f0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
34400 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
34410 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
34420 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
34430 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
34440 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
34450 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
34460 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
34470 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
34480 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
34490 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
344a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
344b0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
344c0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
344d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
344e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
344f0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
34500 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
34510 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
34520 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34530 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
34540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34550 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
34560 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
34570 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
34580 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
34590 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
345a0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
345b0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
345c0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
345d0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
345e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
345f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34600 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
34610 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
34620 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
34630 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
34640 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
34650 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
34660 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
34670 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34680 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34690 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
346a0 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
346b0 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
346c0 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
346d0 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
346e0 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
346f0 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
34700 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
34710 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
34720 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
34730 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
34740 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
34750 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
34760 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
34770 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
34780 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
34790 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
347a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
347b0 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
347c0 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
347d0 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
347e0 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
347f0 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
34800 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
34810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34830 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
34840 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
34850 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
34860 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
34870 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
34880 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
34890 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
348a0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
348b0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
348c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
348d0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
348e0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
348f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
34900 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
34910 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
34920 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
34930 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
34940 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
34950 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
34960 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
34970 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
34980 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
34990 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
349a0 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
349b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
349c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
349d0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
349e0 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
349f0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
34a00 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
34a10 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
34a20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
34a30 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
34a40 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
34a50 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
34a60 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
34a70 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34a80 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
34a90 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
34aa0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
34ab0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
34ac0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
34ad0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34ae0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34af0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
34b00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
34b10 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
34b20 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
34b30 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
34b40 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34b50 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
34b60 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
34b70 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
34b80 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
34b90 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
34ba0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
34bb0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34bc0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
34bd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
34be0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
34bf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34c10 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
34c20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34c30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34c40 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34c50 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34c60 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
34c70 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
34c80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34c90 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
34ca0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
34cb0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
34cc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34cd0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34ce0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34cf0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34d00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34d10 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
34d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34d30 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34d40 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34d50 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
34d60 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
34d70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34d80 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
34d90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34da0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
34db0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34dc0 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
34dd0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34de0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34df0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
34e00 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
34e10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34e20 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
34e30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34e40 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34e50 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
34e60 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
34e70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34e80 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
34e90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34ea0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
34eb0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
34ec0 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
34ed0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
34ee0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34ef0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
34f00 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
34f10 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
34f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34f30 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
34f40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
34f50 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
34f60 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
34f70 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
34f80 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
34f90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34fa0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
34fb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
34fc0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
34fd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34fe0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
34ff0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
35000 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
35010 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
35030 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
35040 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
35050 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
35060 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
35070 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
35080 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
35090 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
350a0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
350b0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
350c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
350d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
350e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
350f0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
35100 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
35110 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
35120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
35130 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
35140 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
35150 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35160 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
35170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35180 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
35190 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
351a0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
351b0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
351c0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
351d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
351e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
351f0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
35200 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
35210 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
35220 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
35230 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
35240 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35250 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
35260 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
35270 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35280 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
35290 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
352a0 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
352b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
352c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
352d0 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
352e0 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
352f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
35300 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
35310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35320 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
35330 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
35340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35350 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
35360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35370 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
35380 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
35390 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
353a0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
353b0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
353c0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
353d0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
353e0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
353f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
35400 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
35410 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
35420 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
35430 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
35440 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
35450 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
35460 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
35470 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
35480 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35490 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
354a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
354b0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
354c0 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
354d0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
354e0 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
354f0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
35500 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35510 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
35520 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
35530 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
35540 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
35550 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
35560 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
35570 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
35580 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
35590 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
355a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
355b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
355c0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
355d0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
355e0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
355f0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
35600 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
35610 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
35620 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
35630 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
35640 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
35650 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
35660 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
35670 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
35680 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
35690 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
356a0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
356b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
356c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
356d0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
356e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
356f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35700 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35710 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
35720 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
35730 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
35740 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
35750 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
35760 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35770 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
35780 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
35790 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
357a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
357b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
357c0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
357d0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
357e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
357f0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
35800 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
35810 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
35820 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
35830 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
35840 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35850 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
35860 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
35870 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
35880 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35890 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
358a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
358b0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
358c0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
358d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
358e0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
358f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35900 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35910 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
35920 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35930 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35940 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35950 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35960 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35970 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35980 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
35990 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
359a0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
359b0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
359c0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
359d0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
359e0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
359f0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35a00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35a10 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
35a20 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35a30 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35a40 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35a50 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35a60 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
35a70 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
35a80 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
35a90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
35aa0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
35ab0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
35ac0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
35ad0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
35ae0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
35af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35b00 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
35b10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35b20 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
35b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35b40 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
35b50 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
35b60 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
35b70 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
35b80 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
35b90 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
35ba0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
35bb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35bc0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35bd0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
35be0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35bf0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
35c00 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35c10 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35c20 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
35c30 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
35c40 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
35c50 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
35c60 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
35c70 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
35c80 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
35c90 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35ca0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35cb0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35cd0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
35ce0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35cf0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35d00 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
35d10 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
35d20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35d30 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
35d40 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
35d50 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
35d60 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
35d70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
35d80 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
35d90 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
35da0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
35db0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
35dc0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
35dd0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
35de0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
35df0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
35e00 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
35e10 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
35e20 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
35e30 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
35e40 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
35e50 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35e60 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
35e70 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
35e80 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
35e90 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
35ea0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
35eb0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
35ec0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
35ed0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
35ee0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
35ef0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
35f00 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
35f10 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
35f20 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
35f30 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
35f40 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
35f50 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
35f60 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
35f70 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
35f80 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
35f90 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
35fa0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
35fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35fc0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
35fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35fe0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
35ff0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
36000 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
36010 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36020 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
36030 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
36040 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36050 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
36060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36070 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
36080 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
36090 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
360a0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
360b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
360c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
360d0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
360e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
360f0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
36100 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
36110 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
36120 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
36130 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
36140 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
36150 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36160 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
36170 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
36180 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
36190 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
361a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
361b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
361c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
361d0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
361e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
361f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
36200 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
36210 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
36220 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
36230 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
36240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36250 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
36260 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
36270 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
36280 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
36290 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
362a0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
362b0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
362c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
362d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
362e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
362f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
36300 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
36310 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
36320 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
36330 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
36340 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
36350 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
36360 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
36370 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
36380 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36390 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
363a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
363b0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
363c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
363d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
363e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
363f0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
36400 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
36410 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
36420 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36430 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
36440 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
36450 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
36460 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
36470 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
36480 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
36490 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
364a0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
364b0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
364c0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
364d0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
364e0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
364f0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
36500 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36520 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36530 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
36540 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36550 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36560 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
36580 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
36590 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
365a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
365b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
365c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
365d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
365e0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
365f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
36600 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
36610 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36620 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
36630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36640 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
36650 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
36660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
36670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
36680 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
36690 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
366a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
366b0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
366c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
366d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
366e0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
366f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36700 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36710 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36730 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
36740 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36750 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36760 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
36770 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
36780 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36790 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
367a0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
367b0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
367c0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
367d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
367e0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
367f0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36810 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36820 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
36830 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
36840 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36850 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
36860 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
36870 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
36880 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36890 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
368a0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
368b0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
368c0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
368d0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
368e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
368f0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36900 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36910 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36920 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36930 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36940 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36950 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36960 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36970 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36980 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36990 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
369a0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
369b0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
369c0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
369d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
369e0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
369f0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36a00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36a10 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36a20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36a30 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36a40 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36a50 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36a60 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36a70 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36a80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36a90 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36aa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
36ab0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36ac0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36ad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36ae0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
36af0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36b00 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36b10 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36b20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36b30 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36b40 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36b50 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36b60 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36b70 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
36b80 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
36b90 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36ba0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36bb0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
36bc0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
36bd0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
36be0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
36bf0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36c00 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36c10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36c20 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
36c30 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
36c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36c50 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
36c60 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36c70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36c80 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
36c90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
36ca0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36cb0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36cd0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36ce0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36cf0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36d00 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
36d10 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
36d20 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
36d30 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
36d40 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
36d50 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
36d60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36d70 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
36d80 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
36d90 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
36da0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
36db0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36dc0 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36dd0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36de0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36df0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36e00 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
36e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36e20 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
36e30 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
36e40 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
36e50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
36e60 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36e70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
36e80 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
36e90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
36ea0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
36eb0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
36ec0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
36ed0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36ee0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
36ef0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
36f00 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
36f10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
36f20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36f30 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
36f40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36f50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36f60 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
36f70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
36f80 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
36f90 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
36fa0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
36fb0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
36fc0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
36fd0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
36fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36ff0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
37000 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
37010 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
37020 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
37030 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
37040 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
37050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37060 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
37070 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
37080 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
37090 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
370a0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
370b0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
370c0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
370d0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
370e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
370f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37100 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37110 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
37120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37130 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37140 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
37150 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37160 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
37170 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
37180 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
37190 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
371a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
371b0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
371c0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
371d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
371e0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
371f0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
37200 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
37210 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37220 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
37230 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
37240 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
37250 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
37260 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
37270 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
37280 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37290 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
372a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
372b0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
372c0 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
372d0 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
372e0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
372f0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
37300 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37310 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
37320 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37330 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
37340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37350 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
37360 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
37370 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
37380 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
37390 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
373a0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
373b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
373c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
373d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
373e0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
373f0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
37400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
37410 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37420 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
37430 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37440 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
37450 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
37460 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
37470 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
37480 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
37490 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
374a0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
374b0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
374c0 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
374d0 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
374e0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
374f0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
37500 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
37510 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
37520 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
37530 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
37540 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
37550 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
37560 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
37570 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
37580 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
37590 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
375a0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
375b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
375c0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
375d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
375e0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
375f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37600 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
37610 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
37620 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
37630 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
37640 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37650 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
37660 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
37670 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
37680 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
37690 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
376a0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
376b0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
376c0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
376d0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
376e0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
376f0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
37700 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
37710 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
37720 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
37730 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
37740 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
37750 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
37760 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
37770 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
37780 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
37790 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
377a0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
377b0 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
377c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
377d0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
377e0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
377f0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
37800 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
37810 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
37820 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37830 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
37840 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
37850 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
37860 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
37870 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
37880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37890 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
378a0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
378b0 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
378c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
378d0 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
378e0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
378f0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
37900 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
37910 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37920 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
37930 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
37940 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
37950 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
37960 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
37970 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
37980 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
37990 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
379a0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
379b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
379c0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
379d0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
379e0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
379f0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
37a00 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
37a10 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37a20 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
37a30 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37a40 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
37a50 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
37a60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
37a70 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
37a80 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
37a90 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
37aa0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37ab0 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
37ac0 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
37ad0 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
37ae0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
37af0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
37b00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
37b10 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
37b20 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
37b30 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
37b40 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
37b50 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
37b60 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
37b70 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
37b80 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
37b90 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
37ba0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
37bb0 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
37bc0 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
37bd0 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
37be0 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
37bf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
37c00 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
37c10 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
37c20 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
37c30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
37c40 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
37c50 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
37c60 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
37c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37c80 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
37c90 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
37ca0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
37cb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
37cc0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
37cd0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
37ce0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
37cf0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
37d00 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
37d10 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
37d20 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
37d30 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
37d40 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
37d50 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37d60 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
37d70 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
37d80 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37d90 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
37da0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
37db0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
37dc0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
37dd0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
37de0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
37df0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
37e00 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
37e10 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37e20 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
37e40 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
37e50 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
37e60 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
37e70 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
37e80 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
37e90 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
37ea0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
37eb0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
37ec0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
37ed0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
37ee0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
37ef0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
37f00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
37f10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37f20 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
37f30 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
37f40 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
37f50 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
37f60 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37f70 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
37f80 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
37f90 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
37fa0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
37fb0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
37fc0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
37fd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
37fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
37ff0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
38000 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
38010 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
38020 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
38030 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38040 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
38050 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
38060 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
38070 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
38080 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
38090 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
380a0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
380b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
380c0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
380d0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
380e0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
380f0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
38100 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38110 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38120 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
38130 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
38140 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
38150 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
38160 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
38170 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
38180 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
38190 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
381a0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
381b0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
381c0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
381d0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
381e0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
381f0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
38200 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38210 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
38220 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
38230 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
38240 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
38250 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
38260 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38270 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
38280 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
38290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
382a0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
382b0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
382c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
382d0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
382e0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
382f0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
38300 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
38310 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
38320 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
38330 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
38340 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
38350 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
38360 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
38370 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
38380 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
38390 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
383a0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
383b0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
383c0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
383d0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
383e0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
383f0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
38400 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
38410 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
38420 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
38430 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
38440 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
38450 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
38460 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38470 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
38480 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
38490 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
384a0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
384b0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
384c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
384d0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
384e0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
384f0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
38500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38510 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
38520 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
38530 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
38540 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
38550 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
38560 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
38570 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38580 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
38590 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
385a0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
385b0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
385c0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
385d0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
385e0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
385f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38610 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
38620 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38630 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
38640 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
38650 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
38660 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
38670 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
38680 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
38690 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
386a0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
386b0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
386c0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
386d0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
386e0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
386f0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
38700 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,in